Quickstart: a verified, audience-bound, HITL-gated effecting object¶
This page takes you from install to a complete N-AALP lifecycle — build, validate, sign, verify, human-approve, execute, and single-use-consume — in one runnable script, in the Python application core. Every step below is real code: no mocked cryptography, no narrated behavior. Run the script yourself and compare your output to what is printed here.
What you will build¶
A destructive action — cancelling a running workflow task — that:
- Is validated for semantic correctness before it is ever signed.
- Is signed with a real post-quantum identity (ML-DSA-65, FIPS 204) and verified offline.
- Is bound to an audience (the authority allowed to act on it).
- Cannot execute until a human approves it through a real, single-use N-AALP approval object.
- Cannot be replayed: the same approval, used a second time, is refused fail-closed.
Install¶
The Python core (naalp) and the ecosystem packages used in this quickstart
(naalp_codec, naalp_validator, naalp_hitl) live in this repository:
- The core SDK:
impl/python/naalp(see the Python SDK guide for the standalonepip install naalppath). - The ecosystem packages:
ecosystem/naalp-codec(the blessed deterministic-CBOR codec binding — re-exports the Part-1 codec directly, never a second encoder),ecosystem/naalp-validator,ecosystem/naalp-hitl(published to PyPI once the supply-chain task lands; until then, import them directly from the repo).
Dependencies: dilithium-py>=1.4.0 (deterministic ML-DSA) and cryptography>=42
(Ed25519). Everything else is the Python standard library.
No API key, no network call, and no external service is required anywhere in this walkthrough — every signature, verification, and ledger append below runs entirely offline, on your machine.
The full script¶
The script behind this page lives at
docs/examples/e5_quickstart.py. Run it from the
repository root:
The five steps below are that same script, in order, with real output from a run.
Step 1 — a real post-quantum agent identity¶
The signer id is a pure function of the public key (no certificate authority):
from naalp import cose, identity
seed = bytes([0x11]) * 32 # a real 32-byte key seed in production
pk = cose.mldsa_keygen("ML-DSA-65", seed)
sid = identity.signer_id(cose.ALG_MLDSA65, pk)
Step 2 — build the candidate object and validate it before signing¶
The args body is built with naalp_codec's own value classes (U/T/M) — the
blessed codec binding, so a caller never hand-rolls a second encoder. Then
naalp_validator.validate() checks CDDL structure, the channel/kind/effect registry, and
the consume-once audience rule against an unsigned candidate — catching a
hallucinated or malformed object before it is ever signed, let alone sent.
from naalp import envelope, policy
from naalp_codec import M, T, U
from naalp_validator import validate
WORKFLOW_CHANNEL, TASK_CANCEL = 0x0011, 2 # Workflow channel: declared effect = DESTRUCTIVE
AUDIENCE = "svc:workflow-cancel-quickstart"
args = M([(U(1), T("task-4821")), (U(2), T("cancel: upstream vendor SLA breach"))])
candidate = envelope.Object(
kind=TASK_CANCEL, channel=WORKFLOW_CHANNEL, signer=sid.encode("utf-8"),
created=1785000000000, effect=policy.DESTRUCTIVE, profile=cose.PROFILE_PUBLIC,
body=args, audience=AUDIENCE,
)
result = validate(candidate)
Step 3 — sign it, then verify it offline¶
signed_bytes = envelope.sign(candidate, cose.ALG_MLDSA65, seed)
verified = envelope.verify(
cose.PROFILE_PUBLIC, cose.ALG_MLDSA65, pk,
lambda c, k: (c, k) == (WORKFLOW_CHANNEL, TASK_CANCEL), signed_bytes,
)
signed object: 3611 bytes, content id 20305d64387a0f68...
verify(): channel=0x0011 kind=2 effect=3 audience='svc:workflow-cancel-quickstart'
This is the verified effecting object: a signed, offline-verifiable, audience-bound
N-AALP object. It is not yet allowed to take effect — its effect class (destructive)
requires a human sign-off first.
Step 4 — gate the side effect behind HITL¶
naalp_hitl.HITLInterceptor pauses any action whose effect meets or exceeds a
configurable threshold (non_idempotent_write by default), routes a real
ApprovalRequest to a human interface, and resumes only after a real signed approval —
bound to the exact args and audience above — has been verified and durably consumed.
from naalp import approval
from naalp_hitl import HITLInterceptor, PendingAction, TerminalFrontend
ledger = approval.open_ledger("consume.wal") # a real durable, hash-chained, single-writer ledger
approver_seed = bytes([0x22]) * 32
approver_pk = cose.mldsa_keygen("ML-DSA-65", approver_seed)
def _cancel_task():
return "TASK_CANCELLED" # the real side effect, run only after approval
action = PendingAction(
kind="workflow.task_cancel", effect=policy.DESTRUCTIVE, args=args,
args_summary="cancel task-4821 (upstream vendor SLA breach)", execute=_cancel_task,
)
frontend = TerminalFrontend("ops-approver-1", approver_seed) # a real terminal prompt
interceptor = HITLInterceptor(
ledger, cose.ALG_MLDSA65, approver_pk, AUDIENCE, "quickstart-interceptor", frontend,
)
outcome = interceptor.intercept(action)
Running this prompts the terminal for a real y/N decision. In the script, that keystroke
is scripted to "y" so the demo runs unattended — everything downstream of it (signing
the approval, verifying it, appending to the durable ledger, and only then calling
execute()) is real, unfaked code:
================================================================
N-AALP HITL approval request
kind: workflow.task_cancel
effect: destructive (3)
content-id: 2030f720dd659cdd75d935ee1f5994b72230118e07ebc3871583d1bd956d1c06c46f4e38f42acf09732ff2607ca4c10fc3dc
args: cancel task-4821 (upstream vendor SLA breach)
audience: svc:workflow-cancel-quickstart
================================================================
intercept() outcome: TASK_CANCELLED
action actually executed: ['TASK_CANCELLED']
Step 5 — fail closed on replay¶
The approval above was bound to a single content id. Minting a second approval for the identical action, consuming it once, and then replaying that exact same approval object demonstrates the ledger's single-use guarantee:
first = interceptor.verify_and_consume(rec, sig, args_id, policy.DESTRUCTIVE) # OK
second = interceptor.verify_and_consume(rec, sig, args_id, policy.DESTRUCTIVE) # raises
first consume of this approval object: OK (ledger entries: 2)
replay of the SAME approval object rejected fail-closed: kind=AlreadyConsumed
No partial state change occurs on the rejected replay: AlreadyConsumed is raised before
execute() would ever be reached, and the ledger records exactly one append per approval
object, ever.
What just happened¶
You built an object that was:
- Semantically validated before it was signed (
naalp_validator). - Cryptographically signed with a post-quantum identity and offline-verified
(
naalp.envelope,naalp.cose). - Audience-bound — the object itself, and the approval that authorized it, both name the exact authority allowed to act on it.
- Gated on a human decision, paused and resumed by a real interceptor
(
naalp_hitl), never executed without a verified approval. - Single-use: the approval that authorized it cannot be replayed.
Where to go next¶
- Cookbook — the four agent patterns (ReAct, Plan-and-Execute, multi-agent, HITL) as runnable recipes.
- The object model — the full signed envelope this quickstart built one field at a time.
- Worked example — the same object model, byte by byte.
- The twenty channels — every registered channel/kind/effect
combination, including
Workflow/TaskCancelused above.