Guardian Auth Signature Flows

Guardian Auth Signature Flows

Overview

Use this skill for the repo's most fragile crypto-adjacent flows. Keep scheme handling explicit, validate boundary conversions, and verify both Falcon and ECDSA whenever the touched path supports both.

Read First

Read these files before editing:

• AGENTS.md
• crates/server/src/ack/*
• crates/server/src/metadata/auth/*
• crates/client/src/auth/*
• crates/client/src/keystore/*
• packages/guardian-client/src/auth-request.ts
• packages/guardian-client/src/conversion.ts
• packages/miden-multisig-client/src/utils/signature.ts
• packages/miden-multisig-client/src/utils/encoding.ts
• references/auth-surfaces.md

Inspect example surfaces too if the changed auth or signature behavior reaches execution or browser signers.

Workflow

1. Classify the signature path. Determine whether the task affects:
   • request auth metadata
   • proposal signatures
   • guardian ack signing
   • keystore or signer abstractions
   • signature encoding or decoding
   • scheme selection or scheme-specific public key handling
2. Edit the lowest boundary first.
   • server verification or signing logic
   • Rust client auth or signer logic
   • TS HTTP auth or signature utilities
3. Verify conversion boundaries explicitly. Normalize external hex, bytes, base64, public keys, and commitments at the boundary module instead of scattering ad hoc conversion logic.
4. Re-check both schemes when the path supports both. Falcon-only or ECDSA-only paths can stay narrow, but mixed flows must be validated under each scheme.
5. Expand upward to multisig execution or examples if the changed signature shape is consumed there.

Guardrails

• Do not branch on free-form error strings in core logic.
• Do not introduce implicit crypto conversions in feature code.
• Do not drop public key information for ECDSA flows that require it downstream.
• Preserve explicit x-pubkey, x-signature, and x-timestamp behavior when touching request signing.
• Preserve ack_sig, ack_pubkey, and ack_scheme behavior when touching execution or proposal flows.
• If a path uses both Falcon and ECDSA, test both. Do not infer parity from one scheme.

Validation

Default targeted checks:

cargo test -p guardian-client
cargo test -p guardian-server
cd packages
npm ci
npm test -w @openzeppelin/guardian-client

Expand when the auth or signature change crosses into multisig execution:

• cargo test -p miden-multisig-client
• cd packages && npm run build -w @openzeppelin/guardian-client && npm test -w @openzeppelin/miden-multisig-client
• smoke-test-rust-multisig-sdk
• smoke-test-ts-multisig-sdk

Output Shape

Report:

• signature path touched
• schemes exercised
• boundary modules updated
• downstream consumers checked
• tests and smoke coverage
• unresolved assumptions