DOCS / REFERENCE / AUTHORIZATION MODEL

Authorization model

COPIED FROM chimpdao-contracts/docs/AUTH.md · REVISION 6fd752349933 · Repository ↗

How chip signatures authorize state changes. Shared crypto lives in contracts/chip-auth/.

Two models, differing in what the chip proves:

Chip is… Mechanism Contracts
Account auth the account’s key CustomAccountInterface; the host builds the payload pocket, account
Presence attestation a second factor beside a wallet call_digest over the specific call nfc-nft, examples/prize

Both bind the call; neither accepts an opaque blob.

Account auth: Pocket and the Chimp account

Both implement __check_auth and sign the same thing, the payload the host computes:

sha256(HashIdPreimage::SorobanAuthorization {
  network_id, nonce, signature_expiration_ledger, invocation
})

invocation is the contract, function name, argument ScVals and sub-invocations being executed. Change the destination or amount and the digest changes. The host enforces replay and expiry, so Pocket keeps no nonce.

CAP-71 added the credential variant sorobanCredentialsAddressV2, whose preimage also carries the authorizing address. The contract sees only the resulting 32-byte payload; the client must sign the right one (Digest / replay matrix).

  • No Pocket transfer entry point. A payment is a plain SAC transfer(pocket, merchant, amount) that the host routes to Pocket’s __check_auth, so the purse works with Blend or any contract without new code.
  • Every Pocket decision is chip-gated, set_owner included: it calls require_auth on the contract’s own address, which routes to __check_auth and binds that call’s arguments. The one exception, apply_upgrade_policy, only carries out a decision the chip already signed. sweep does not exist, so owner is a signpost the card rewrites and there is no path to the float without the chip. A lost card is lost money.
  • Pocket verifies inline. It stores the card’s Curve and calls chimpdao_chip_auth::verify_chip_auth directly. No stored verifier address can be re-pointed, no registry outage can freeze a purse, and __check_auth has no re-entrancy surface.

The signature binds the call because an unbound one is a bearer credential. A signature over an opaque message would tie nothing on chain to token, to or amount, so one (message, auth, nonce) would authorize any transfer of any amount anywhere. A transaction envelope is flooded across the overlay before ledger close, and a transfer that fails leaves its authorization readable on the ledger with its nonce unconsumed. The host payload names the exact invocation, so a leaked entry authorizes only that call, until its expiration ledger.

pocket/src/test.rs pins the binding with a software chip, natively and as built: a_purse_accepts_its_own_chip_on_either_curve, a_purse_refuses_another_card_and_a_signature_over_another_call and a_junk_signature_is_an_invalid_signature.

The Chimp account: same payload, different envelope

A purse is bound to one card, so its envelope carries only the signature. An account holds a set of signers, cards and passkeys, so the envelope also names which one signed and says how:

pub struct CardSigner    { pub key: BytesN<65>, pub curve: Curve }                    // stored, per card
pub struct PasskeySigner { pub key: BytesN<65>, pub credential_id: Bytes,
                           pub rp_id_hash: BytesN<32> }                               // stored, per passkey
pub struct AccountAuth   { pub key: BytesN<65>, pub auth: AccountProof }              // presented per call
pub enum   AccountProof  { <a card proof>, Webauthn(WebauthnAuth) }

__check_auth looks key up in the set the proof’s kind names, Cards for a card proof, Passkeys for Webauthn, never both, and verifies the proof against that stored entry, so naming someone else’s key buys nothing and a key listed as a card is never accepted as a passkey, nor the reverse. A card client builds the same XDR whether or not it knows passkeys exist.

auth_contexts is ignored. Any signer may authorize any context (that is 1-of-n), and not matching on Context keeps the contract indifferent to the variants CAP-85 added. A card and a passkey have exactly the same power. Nothing is hashed on top of the host payload; the account verifies signature_payload as delivered.

Signer management (add_card, remove_card, add_passkey, remove_passkey, abandon) and code changes (upgrade, update, set_upgrade_policy, set_factory) are authorized by the account itself, which routes back through __check_auth, so “an existing signer consents” and “the account authorized it” are the same statement. remove_card and remove_passkey refuse the last signer of either kind (LastSigner, #504), since an account with no signer can never authorize anything again, including adding one. abandon() empties an account deliberately.

contracts/account/src/test.rs (the wire tests, with the cards’ constants and TERMINAL_ACCOUNT_AUTH_WEBAUTHN, TERMINAL_PASSKEY_SIGNER, TERMINAL_VEC_PASSKEYS) decode real client XDR to pin the exact bytes a client builds. Nothing else catches field-order or variant-name drift across repos.

Passkeys (WebAuthn)

A passkey is a P-256 key held by a platform authenticator or a security key. It is verified with the host primitive secp256r1_verify, plus a wrapper: an authenticator signs authenticator_data ‖ sha256(client_data_json), and the browser puts the challenge into client_data_json. The challenge is the host’s signature_payload. verify_webauthn (chip-auth) checks exactly this, then the signature:

  1. authenticator_data is 37 to 512 bytes and its first 32 bytes equal the signer’s stored rp_id_hash.
  2. The flags byte has user presence (0x01) and user verification (0x04) both set.
  3. client_data_json is at most 1024 bytes and starts with the exact bytes {"type":"webauthn.get","challenge":", then base64url(signature_payload) (43 characters, no padding), then ". The payload is encoded and compared as bytes: no JSON parser, no substring search, no base64 decoding.
  4. secp256r1_verify(key, sha256(authenticator_data ‖ sha256(client_data_json)), signature) with signature as raw 64-byte r ‖ s.

Structural failures (1 to 3) make __check_auth return InvalidSignature (#502). A signature that does not verify, or one with a high s, traps, because secp256r1_verify has no fallible form; the client converts an authenticator’s DER signature to raw r ‖ s and normalises s to the lower half of the curve order.

Deliberately not checked: origin and crossOrigin. The relying-party id is chimpdao.xyz for the whole domain, so the landing site, the NFT viewer and a future web app can each ask for a passkey signature; that is safe only while every host under the domain is ChimpDAO’s (CLIENT-INTEGRATION.md § 5.1). Also not checked: the signature counter (synced passkeys report 0 forever), backup flags, attestation and extensions. The serialisation order of client_data_json is fixed by the WebAuthn specification, so a client that orders the fields differently fails closed; the_pinned_assertion_verifies_for_an_account_built_from_the_pinned_signer pins a vector.

credential_id is not trusted: it only lets a client find which stored key to present. The relying-party id is part of the stored signer, so adding a passkey for a different relying party is an explicit, signed add_passkey.

Pocket vs account

sequenceDiagram
  participant Chip
  participant Host as Soroban host
  participant Pocket
  participant Account as Chimp account

  Note over Host: payload = hash of contract, function, args, nonce, expiry
  Chip-->>Host: signature over the payload (signed before submission)

  Note over Host,Pocket: Pocket spend
  Host->>Pocket: __check_auth(payload, ChipAuth, contexts)
  Pocket->>Pocket: verify_chip_auth(payload, stored Chip, stored Curve)

  Note over Host,Account: Account spend, card
  Host->>Account: __check_auth(payload, AccountAuth, contexts)
  Account->>Account: find the named key in Cards
  Account->>Account: verify_chip_auth(payload, that card's key and curve)

  Note over Host,Account: Account spend, passkey
  Host->>Account: __check_auth(payload, AccountAuth{Webauthn}, contexts)
  Account->>Account: find the named key in Passkeys
  Account->>Account: verify_webauthn(payload, its rp_id_hash, its key, assertion)

They differ only in how the signer is found: a purse has one card in storage; an account has two sets and the envelope names one signer and its kind. Each then runs a linked verification over the same host payload, and the host owns binding, replay and expiry. Do not add an app nonce to either.

Presence attestation: nfc-nft

The wallet authorizes through its own Soroban auth, and the chip separately proves the physical object was on the reader. nfc-nft verifies that itself:

digest = sha256(domain ‖ contract_xdr ‖ fn_name_xdr ‖ args_xdr ‖ nonce_xdr)

Built by call_digest. Every attested field is inside the hash, so an attestation is good for one call to one function of one contract with one set of arguments, once. domain is per contract family (chimpdao.nfc-nft.v3, chimpdao.prize.v1) and its suffix is bumped whenever the digest construction changes.

verify_for_card(public_key, digest, auth) is public but stateless: it returns a bool over the registry’s stored key and curve and never produces a signature. Replay is the caller’s problem; integrators bring their own domain and nonce (examples/prize).

Verification is linked, not delegated

There are no verifier contracts. chimpdao-chip-auth is an rlib implementing both algorithms once; pocket, account and nfc-nft link it and call verify_chip_auth directly. The account’s WebAuthn check is a module of the account itself and is linked the same way.

A verifier reached through a stored contract address is a pointer someone can re-aim, and every purse’s liveness would hang on the contract behind it. Linking removes both: a purse’s __check_auth reads only its own storage. The cost is that a crypto fix is a fleet upgrade rather than one contract, which is what UpgradePolicy is for; the crypto is ~1–2 KB of wasm.

nfc-nft.verify_for_card serves integrators: an outside contract links the rlib only for call_digest (a hash) and cross-calls verify_for_card for the crypto.

Auth matrix

Entry Wallet require_auth Chip Notes
nfc mint admin attestation over [pubkey, curve, upgrade_policy, uri] provisions the trio: records curve and pubkey↔token, deploys the purse, writes Owner once. The destination is derived, so the attestation is the whole holder-side authorization. See ARCHITECTURE.md
nfc set_factory admin — names the factory mint deploys through; mint refuses without it (#106)
nfc clawback admin — central escape hatch; emits transfer (purse → admin). The chip stays registered, so it cannot be minted again, and its purse stays where it is
nfc, collection, factory set_admin admin — hands the role over at once, no second step; emits SEP-41 set_admin
nfc set_trait / set_trait_metadata_uri admin — ERC-7496; tier is the only trait; set_trait emits set_trait and metadata
nfc pocket / curve / trait_value(s) / verify_for_card and the token views — — public views
Pocket: any call it authorizes (SAC transfer, vault deposit, pool submit) — __check_auth the chip is the account
Pocket set_owner — __check_auth repoints the signpost when the card changes root
Pocket set_upgrade_policy — __check_auth the decision to join or leave the fleet
Pocket apply_upgrade_policy — — permissionless: only makes the executable match a choice the chip already signed. Single-shot: refuses (#405) unless a chip-signed decision is pending. Emits apply_upgrade_policy
Pocket upgrade — __check_auth Manual only; refuses under Managed (#403)
router batch caller → that address’s __check_auth (purse or account) — pass-through: no admin, no upgrade path, no state. Anchors every leg into one condensed tree: one entry, one nonce, one tap. A move between two of the holder’s balances adds a second, non-root entry for the destination, discovered with record_allow_nonroot for an account and declared as a cosigner tree for a purse. A non-root entry authorizes its own invocation wherever the host finds it, not the batch around it, so a move that must be all-or-nothing across two signers needs one signer’s root entry over the whole tree
factory set_pocket_wasm_hash admin — re-points every Managed purse at once (CAP-85); records the hash in the Pocket history and moves the epoch
factory set_account_wasm_hash admin — re-points every account that opted into Managed at once (CAP-85) and is the hash update() installs for Manual ones; records the hash in the account history and moves the epoch
factory seed_history admin — adds older hashes to a history so contracts still running them are recognised as behind. Idempotent, never moves a head or an entry; grants the admin no power it lacks, since the admin already controls the head
factory create_account / upgrade admin — deploys a purse from the card’s key; idempotent. When the purse already exists it is returned as is, whatever curve and upgrade_policy were passed
factory refresh — — permissionless keepalive: extends the factory and the "pocket" and "account" reference entries that exist. Reads no argument, moves no head, history, epoch or authorization, and emits no event
factory fleet / pocket_wasm_hash / account_wasm_hash / get_account — — public views
account add_card / remove_card / add_passkey / remove_passkey / abandon the account itself → __check_auth any signer on it, card or passkey 1-of-n; remove_card and remove_passkey refuse the last signer of either kind. A handover is add_card / remove_card plus the purse’s chip-signed set_owner; nothing moves (ARCHITECTURE.md)
account upgrade / update / set_upgrade_policy the account itself → __check_auth any signer on it upgrade(hash) takes a signer-chosen hash; update() takes none and installs the factory’s account_wasm_hash. Both refuse under Managed (#511). set_upgrade_policy records the decision and marks one apply as owed only when it changes the policy
account apply_upgrade_policy — — permissionless: only makes the executable match a decision a signer already signed. Single-shot: refuses (#512) unless one is pending. Emits apply_upgrade_policy
account set_factory the account itself → __check_auth any signer on it once only (#514). The one trust point of update(): clients take the address from their own configuration and show it in full. Resets a stored Managed to Manual and emits the SEP-50 mint
account cards / passkeys / has_card / has_passkey / factory / version / upgrade_policy and the SEP-50 views — — public views
collection create_collection / upgrade admin — deploys nfc-nft instances; ownership index
collection assign_collectible the calling nfc-nft contract, which must be a registered collection — updates the ownership index on mint and clawback

Digest / replay matrix

The terminal builds both smart-account signatures over the host payload, with the envelope from chipAuthForDigest (purse) or accountChipSignature (account) in src/chain/chip-auth.ts. Who authorizes decides when the chip signs.

  • Plain-wasm authorizer (the Chimp account): a recording simulation reports the entries the transaction needs, the signer signs each payload (signAuthEntries), a chip or a passkey, and the footprint is refitted in enforce mode before submission. A passkey signs the same payload as the WebAuthn challenge.
  • Account that follows the fleet (Managed) and purse: the authorization tree is declared and signed before anything is simulated, because a recording simulation fails inside the host when the authorizer’s executable is a fleet reference (preSignedAuthEntries); a purse is signed first whatever its policy. A wrong declaration fails in enforce-mode preflight, and a signed tree can never authorize more than it declares (CLIENT-INTEGRATION.md; chimpdao-terminal docs/architecture.md § Auth).

CAP-71’s sorobanCredentialsAddressV2 signs a different preimage, HashIdPreimageSorobanAuthorizationWithAddress (V1’s plus the authorizing address). A recording simulation returns V2 entries; entries the client builds are V1. The client keeps the variant an entry arrived with and hashes the matching preimage.

Path What is signed Envelope Replay stops at
Pocket (__check_auth) host SorobanAuthorization preimage (V1, or V2 …WithAddress when the entry carries V2 credentials) ChipAuth host nonce + expiration ledger
Account (__check_auth), card the same preimage AccountAuth { key, auth: <a card proof> } host nonce + expiration ledger
Account (__check_auth), passkey the same preimage, as the WebAuthn challenge AccountAuth { key, auth: Webauthn } host nonce + expiration ledger
nfc-nft attestation call_digest(domain, contract, fn, args, nonce) ChipAuth per-chip monotonic nonce
prize attestation same, domain chimpdao.prize.v1 ChipAuth its own per-chip nonce

There is one smart-account digest, the host’s. Its V1 preimage carries the invocation and not the authorizing address, so a purse and an account that list the same card verify the same signature over it. A signature moves between the two only when the invocation names neither. Every call here names its authorizer: a self-authorized call is made on the contract itself, a payment carries from, and router.batch carries caller. A third-party function that requires the authorization of an address absent from its arguments does not, and one tap could then count for both; V2 credentials bind the address. Attestations are separated from both by domain.

Trust model

Layer Who can hurt you
Central (collection, factory, nfc mint/clawback/upgrade) protocol admin
Fleet code protocol admin: set_pocket_wasm_hash replaces the code of every Managed purse in one call, which is control of those purses and their funds; set_account_wasm_hash does the same for every account that opted into Managed, which holds the holder’s primary funds and signer sets. A Manual purse or account is out of reach of a push, and a holder who opts in must be told so before the signature. A release is canaried before it is pinned (RELEASE.md)
Router nobody: no admin, no upgrade path, holds nothing
Pocket whoever holds the physical chip, bounded by the purse float and its positions; for a Managed purse, also the fleet admin
Pocket recovery nobody: sweep does not exist
Chimp account any one of its signers (1-of-n), card or passkey, as peers; a lost or stolen signer is live until another signer removes it. A passkey is only as safe as the platform account that syncs it, which is that platform’s property, not the contract’s
Account recovery none by ChimpDAO, ever. A Main is controlled by its signers; while it keeps one, any signer can remove a lost one. Losing every signer loses the account. remove_card and remove_passkey refuse the last signer of either kind; only abandon empties an account
NFT ownership fixed at mint to the card’s own purse: no destination to choose, no later write

There is one admin address per central contract (collection, each nfc-nft, the factory). set_admin rotates it, one contract at a time and without a confirmation step, so the mainnet admin should be a multisig account. create_collection gives a new nfc-nft the registry’s admin at that moment; afterwards the two are independent.

Recorded design notes

Behaviour that a reviewer will ask about and that is kept on purpose.

  • call_digest writes domain without a length prefix. The domains in use are fixed and none is a prefix of another. Prefixing would change every signed digest in the terminal and iOS.
  • nfc-nft’s per-chip nonce guards a call that succeeds at most once, because mint refuses a card that has a token before it checks the signature. It is bound into the digest and kept.
  • verify_for_card builds a Hash<32> from bytes through the SDK’s TryFromValForContractFn, which the SDK marks internal. The SDK offers no public constructor.
  • The factory adopts a purse that already exists. mint does not compare its curve or policy with the attested ones; only the admin can create a purse before the mint.
  • The router holds nothing by design. An asset sent to its address, or a role or allowance granted to it, is usable by whoever calls batch. Never fund or grant anything to it.
  • A passkey never authorizes a purse. A purse answers to its chip alone, sweep does not exist, and Pocket::owner grants nothing, so a Main’s signers, passkeys included, have no path to a card’s float. a_passkey_proof_cannot_authorize_a_purse pins it.
  • upgrade(hash) never calls the factory, so an outage or a bad pin can never be the reason an account cannot be upgraded; update() and apply_upgrade_policy are the only paths that read it.