Python Ucan
Project description
py-ucan
This is a Python library to help the web applications make use of UCANs in their authorization flows. To learn more about UCANs and how you might use them in your application, visit ucan website or read the spec.
Contents
Installation ⇧
pip install -U py-ucan
Usage ⇧
Ucan objects ⇧
All the objects are based on Pydantic v2 models. Ideally you would only need to use model_validate
, model_validate_json
and model_dump
from the pydantic model API, but please go through their docs for advanced usage.
NOTE: Ojects can be instantiated with field names in camel case, but to access those fields, you need to use their snake case names.
ucan.ResourcePointer
from ucan import ResourcePointer
# -- from encoded value
resource = ResourcePointer.decode("fileverse://solo.fileverse.io")
# -- from kwargs: snake case
resource = ResourcePointer(scheme="fileverse", hier_part="//solo.fileverse.io")
# -- from kwargs: camel case
resource = ResourcePointer(scheme="fileverse", hierPart="//solo.fileverse.io")
# -- from dict: snake case
resource = ResourcePointer.model_validate({"scheme": "fileverse", "hier_part": "//solo.fileverse.io"})
# -- from dict: camel case
resource = ResourcePointer.model_validate({"scheme": "fileverse", "hierPart": "//solo.fileverse.io"})
# -- from json: snake case
resource = ResourcePointer.model_validate_json('{"scheme": "fileverse", "hier_part": "//solo.fileverse.io"}')
# -- from json: camel case
resource = ResourcePointer.model_validate_json('{"scheme": "fileverse", "hierPart": "//solo.fileverse.io"}')
# access values
print(resource.scheme, resource.hier_part)
# output: fileverse //solo.fileverse.io
# dump to python dict
# all the objects above will dump to a dict with camel case fields
print(resource.model_dump())
# output: {'scheme': 'fileverse', 'hierPart': '//solo.fileverse.io'}
# encode as string
print(resource.encode())
# or
print(str(resource))
# output: fileverse://solo.fileverse.io
ucan.Ability
from ucan import Ability
# -- from encoded value
ability = Ability.decode("crud/edit")
# -- from kwargs
ability = Ability(namespace="crud", segments=["edit"])
# -- from dict
ability = Ability.model_validate({"namespace": "crud", "segments": ["edit"]})
# -- from json
ability = Ability.model_validate_json('{"namespace": "crud", "segments": ["edit"]}')
# access values
print(ability.namespace, ability.segments)
# output: crud ['edit']
# dump to python dict
# all the objects above will dump to a dict
print(ability.model_dump())
# output: {'namespace': 'crud', 'segments': ['edit']}
# encode as string
print(ability.encode())
# or
print(str(ability))
# output: crud/edit
ucan.Capability
NOTE: since with
is a reserved keyword in python, the with
field in Capability
is accessible via with_
attribute, but the Capability
model supports loading values having with
field name using a python dict or a JSON string (see examples below).
import json
from ucan import Ability, Capability, ResourcePointer
# --- load `with` value
# loaded from kwargs
resource = ResourcePointer(scheme="https", hier_part="//app.example.com")
# or loaded from string
resource = ResourcePointer.decode("https:////app.example.com")
# or an encoded string
resource = "https://app.example.com" # encoded value
# or a dict with snake case field names
resource = {"scheme": "https", "hier_part": "//app.example.com"}
# or a dict with camel case field names
resource = {"scheme": "https", "hierPart": "//app.example.com"}
# --- load `can` value
# loaded from kwargs
ability = Ability(namespace="crud", segments=["view"])
# or loaded from string
ability = Ability.decode("crud/view")
# or an encoded string
ability = "crud/view" # encoded value
# or a dict with snake case field names
ability = {"namespace": "crud", "segments": ["view"]}
# --- load `capability` value
# note: all the above variations of `resource` and `ability` are supported.
# -- from kwargs
capability = Capability(with_=resource, can=ability)
# -- or by spreading the dict as kwargs
capability = Capability(**{"with": resource, "can": ability})
# -- from dict
capability = Capability.model_validate({"with": resource, "can": ability})
# or
capability = Capability.model_validate({"with_": resource, "can": ability})
# -- from json
capability = Capability.model_validate_json(
json.dumps({"with": resource, "can": ability})
)
# or
capability = Capability.model_validate_json(
json.dumps({"with_": resource, "can": ability})
)
# access values
# note: `with` field cannot be accessed with the name `with`, use `with_` instead.
# note: print function outputs the str representation of the models
# and since `ResourcePointer` and `Ability` models implement their
# respective `__str__` callbacks, the output is simply their encoded values.
print(capability.with_, capability.can)
# output: https://app.example.com crud/view
# dump to python dict
# all the objects above will dump to a dict
print(capability.model_dump())
"""
output:
{
'with': {'scheme': 'https', 'hierPart': '//app.example.com'},
'can': {'namespace': 'crud', 'segments': ['view']}
}
"""
# encode all capability parts
print(capability.encode())
# output: {'with': 'https://app.example.com', 'can': 'crud/view'}
Parsing UCAN Tokens ⇧
To parse a token without validating its signature or expiry, you need to use the parse
function or Ucan.decode
model function.
import ucan
# receive the token from user request.
encoded_token = "eyJhbG..." # request.headers.get("Authorization") or similar
# using `ucan.parse`
try:
# here `parsed_token` is an instance of `ucan.Ucan`.
parsed_token = ucan.parse(encoded_token)
except ValueError as e:
# Invalid token
pass
# or, using `ucan.Ucan.decode` model function
try:
# here `parsed_token` is an instance of `ucan.Ucan`.
parsed_token = ucan.Ucan.decode(encoded_token)
except ValueError as e:
# Invalid token
pass
Validating UCAN Tokens ⇧
To validate a token, you need to use the validate
function.
import ucan
# receive the token from user request.
encoded_token = "eyJhbG..." # request.headers.get("Authorization") or similar
# parse and validate the token
try:
# here `parsed_token` is an instance of `ucan.Ucan`.
parsed_token = await ucan.validate(encoded_token)
except Exception as e:
# Invalid token
pass
Verifying UCAN Invocations ⇧
Using a UCAN to authorize an action is called "invocation".
To verify invocations, you need to use the verify
function.
import ucan
# receive the token from user request.
encoded_token = "eyJhbG..." # request.headers.get("Authorization") or similar
# generate service keypair
service_key = ucan.EdKeypair.generate()
service_did = service_key.did() # will return "did:key:zabcde..."
# known resource and user to validate against
doc_id = "some-id"
user_did = "did:key:z6Mk..."
result = await ucan.verify(
encoded_token,
# to make sure we're the intended recipient of this UCAN
audience=service_did,
# capabilities required for this invocation & which owner we expect for each capability
required_capabilities=[
ucan.RequiredCapability(
capability=ucan.Capability(
with_=ucan.ResourcePointer(
scheme="fileverse", hier_part="//portal.fileverse.io"
),
can=ucan.Ability(namespace=doc_id, segments=["EDIT", "VIEW"]),
),
# check against a known owner of the `doc_id` resource
root_issuer=user_did,
),
],
)
# result will be one of the following:
# error: ucan.VerifyResultError(ok=False, errors=[Exception("...")]
# success: ucan.VerifyResultOk(ok=True, value=[ucan.Verification(..)])
if isinstance(result, ucan.VerifyResultOk):
# The UCAN authorized the user
pass
else:
# Unauthorized
pass
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.