passkey-kit 0.16.2 → 0.16.4

package/README.md

@@ -5,8 +5,8 @@ A TypeScript SDK for creating and using **smart-wallet accounts on Stellar with
 - **Client (`PasskeyKit`)** — runs in the browser: create/connect wallets, sign transactions, build signer-management transactions. Holds no secrets.
 - **Server (`PasskeyServer`)** — runs server-side: submits transactions through a relayer (fee sponsorship), plus convenience signer-discovery helpers over the keyless Mercury indexer. Holds the relayer secret.
 
-> [!IMPORTANT]
-> **Security.** Review the contract and SDK yourself before holding meaningful value, and read [Caveats](#caveats).
+> [!CAUTION]
+> **Unaudited software.** This repository's smart-wallet contract, SDKs, and relayer proxy have not received an independent third-party security audit. Defects can cause unauthorized transactions, loss of access, or permanent asset loss. Do not store or control assets you cannot afford to lose. Limit balances and signer permissions. Monitor wallets and maintain recovery and authorized upgrade paths. You use this software and related services at your own risk. The software has no warranty; see [LICENCE](./LICENCE), [Caveats](#caveats), and [SECURITY.md](./SECURITY.md).
 
 > [!NOTE]
 > **Looking for context rules, thresholds, and spending-limit policies?** [smart-account-kit](https://github.com/stellar/smart-account-kit) is a sibling SDK built on the audited [OpenZeppelin stellar-contracts](https://github.com/OpenZeppelin/stellar-contracts) account. It uses a different on-chain authorization model (context rules + an auth digest) than passkey-kit's flat `Signatures` map, so the two are not drop-in compatible — pick the model that fits your app.
@@ -70,8 +70,8 @@ import { PasskeyKit } from "passkey-kit";
 const kit = new PasskeyKit({
   rpcUrl: "https://soroban-testnet.stellar.org",
   networkPassphrase: "Test SDF Network ; September 2015",
-  // Canonical v1 smart-wallet WASM hash (testnet); see docs/deployments-*.md
-  walletWasmHash: "fdefad64b96837147e1c333e51f537b696eab925e9f147e63d597c04e3c903f0",
+  // Canonical smart-wallet WASM hash; see docs/deployments-*.md
+  walletWasmHash: "502ea4e7bdb3ea99880941f1d35ceb67fb598692c0bb40f842ef9c9f17d58b58",
 });
 ```
 
@@ -235,7 +235,7 @@ Each method builds an `AssembledTransaction` (`WalletTx`) that wraps one contrac
 | `updateEd25519(publicKey, limits, store, expiration?)` | `update_signer` | Update an Ed25519 signer. |
 | `addPolicy(policy, limits, store, expiration?)` | `add_signer` | Add a policy signer (`policy` = `C…`). Invokes the policy's `install` hook. |
 | `updatePolicy(policy, limits, store, expiration?)` | `update_signer` | Update a policy signer. |
-| `remove(signerKey)` | `remove_signer` | Remove a signer. No policy code runs on this path. |
+| `remove(signerKey)` | `remove_signer` | Remove a signer. A policy entry must pass its own `policy__` check. |
 | `upgrade(newWasmHash)` | `upgrade` | Replace the wallet's WASM (`Buffer`/`Uint8Array`, 32 bytes). |
 | `getSigner(signerKey)` | `get_signer` | Read a signer entry from the ledger (temporary before persistent). Returns `SignerVal \| null`. |
 
@@ -427,6 +427,11 @@ type SignerLimits = Map<string, SignerKey[] | undefined> | undefined;
 - `Map` present but a contract → `undefined` — may authorize any call to that contract, no co-signers.
 - `Map` present, contract → `[keys]` — may authorize calls to that contract **only if every listed key also approves** (required co-signers).
 
+A required policy key must remain installed as a signer and unexpired. Removing
+that policy immediately revokes every signer whose limits require it. A
+`Signature::Policy` always invokes `policy__`, including for the policy's own
+`remove_signer` context.
+
 ```ts
 // This signer may only call C…token, and only alongside a passkey co-signer.
 const limits = new Map([["C…token", [SignerKey.Secp256r1(keyId)]]]);
@@ -450,13 +455,16 @@ Signer and signature expiration are **UNIX timestamps in seconds** (inclusive: v
 ## Caveats
 
 > [!WARNING]
-> These are inherent to the wallet model. The SDK does not guard against them — handle them in your app.
+> These risks are not exhaustive. Tests and reviews do not prove that the software has no defects.
 
+- **Limit value and authority.** Limit wallet balances, signer permissions, policy allowances, and relayer permissions. Monitor wallet activity. Keep independent recovery, submission, and authorized upgrade paths.
+- **Hosted services can fail or return stale data.** Do not treat relayer or indexer responses as authoritative chain state. Confirm security-sensitive state through Stellar RPC.
 - **Keep at least one durable admin signer.** The contract rejects any change that would remove or demote its last durable (`Persistent`, non-expiring) admin signer (`LastAdminSigner = 103`) or leave it without any durable signer (`LastSigner = 104`), so a wallet always retains one signer that cannot evict or expire. Signers outside that guard — `Temporary` storage or with an expiration — lapse on their own: add a replacement *before* removing or demoting an existing signer.
 - **The default deployer is a shared, public keypair — its secret is publicly derivable.** It salts deployment and signs only the CreateContractV2 authorization entry; the relayer supplies the envelope source, sequence, and fees. It never controls the wallet. Its determinism is load-bearing for discovery: overriding `deploySource` changes every derived address and breaks keyId → wallet lookup. Use a separate funded `restoreSource` for `restoreFootprint`; never fund the shared deployer. A third-party `bumpSequence` to `INT64_MAX` no longer blocks the current SDK because it never uses the shared deployer as an envelope source. Full analysis: [`docs/security-deterministic-deployer.md`](docs/security-deterministic-deployer.md).
 - **Deploy front-running remains an accepted residual.** Anyone who learns a `keyId` before deployment could place arbitrary code at the derived address. A signer getter check alone is not proof of ownership, because arbitrary code can answer it however the client expects. Since `0.16.0` `connectWallet` binds accepted code identity (`acceptedWasmHashes`) before reading any signer state, for any address that did not come from trusted local storage. A derivation-resolved address is still not authenticated by that check alone — see the [security analysis](docs/security-deterministic-deployer.md#accepted-residual-address-squatting).
 - **WebAuthn requires User Presence (UP), not User Verification (UV).** The contract requires the UP flag but not UV (biometric/PIN), so it stays compatible with non-UV authenticators. Enforce UV at the client/relayer layer if you need it.
 - **Value-moving policies need a cumulative cap or a co-signer.** A `Signature::Policy` carries no secret, so a per-transfer cap alone is trivially drained by repeated capped transfers. See the [contract interface](#contract-interface) and `sample-policy`.
+- **Existing `binver = 1.0.0` wallets require an authorized upgrade.** Installing the fixed WASM does not change deployed wallet instances. Upgrade each wallet to the canonical `binver = 1.0.1` hash in the current deployment manifest.
 
 ## Contract interface
 
@@ -491,7 +499,7 @@ contractId = sha256(XDR(HashIdPreimage::EnvelopeTypeContractId {
 - The canonical deployer keypair is `Keypair.fromRawEd25519Seed(sha256("kalepail"))`. It salts the deploy and signs the deploy authorization — it never pays fees and never controls the wallet — but its determinism is **load-bearing**: overriding `deploySource` changes every derived address and breaks keyId → wallet discovery.
 - The WASM hash is deliberately **not** in the preimage, so an `upgrade` never moves a wallet's address.
 
-This tuple is normative and must never change. See [`docs/deployments-testnet-2026-07-11.md`](./docs/deployments-testnet-2026-07-11.md) for the canonical WASM hashes, the deployer `G…` address, and the full derivation spec (including the deploy-front-running consequence in [Caveats](#caveats)).
+This tuple is normative and must never change. See [`docs/deployments-2026-08-19.md`](./docs/deployments-2026-08-19.md) for the canonical WASM hash, upload transactions, and upgrade guidance.
 
 ## Repository layout & development
 
@@ -512,6 +520,7 @@ pnpm verify:bindings  # assert the committed bindings match the canonical WASM
 ```
 
 - **[CHANGELOG.md](./CHANGELOG.md)** — the v1 overhaul, by component.
+- **[SECURITY.md](./SECURITY.md)** — supported versions and private vulnerability reporting.
 - **[docs/migration-v1.md](./docs/migration-v1.md)** — upgrading from 0.12.x, with Before/After and a gap analysis.
 - **[docs/releasing.md](./docs/releasing.md)** — the dependency-ordered publish flow.
 

package/SECURITY.md

@@ -0,0 +1,27 @@
+# Security Policy
+
+## Security status
+
+The smart-wallet contract, SDKs, and repository relayer proxy have not received an independent third-party security audit.
+
+Tests and reviews reduce risk. They do not prove that the software has no defects.
+
+Do not store or control assets you cannot afford to lose. Limit balances and permissions. Monitor wallets and maintain recovery and authorized upgrade paths.
+
+## Supported versions
+
+Only the latest npm releases and the canonical smart-wallet WASM receive security fixes.
+
+The current deployment manifest in [`docs/`](./docs/) identifies the canonical WASM. Existing wallet instances do not upgrade automatically.
+
+## Report a vulnerability privately
+
+Do not open a public issue, pull request, discussion, or chat message for a suspected vulnerability.
+
+Email `tyler@stellar.org` with the subject `passkey-kit security report`. If email is unsuitable, request a private channel without including sensitive details.
+
+Include the affected version or commit, impact, reproduction steps, and a minimal proof of concept. Do not include secrets or personal data.
+
+Use local tests or isolated test accounts. Do not test against public user wallets or move assets that you do not own.
+
+The maintainers will confirm receipt, investigate the report, prepare a fix, and coordinate disclosure with the reporter.

package/dist/version.d.ts

@@ -2,6 +2,6 @@
  * Package version — auto-generated from package.json.
  * @packageDocumentation
  */
-export declare const VERSION = "0.16.2";
+export declare const VERSION = "0.16.4";
 export declare const NAME = "passkey-kit";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -4,6 +4,6 @@
  */
 // This file is auto-generated. Do not edit manually.
 // Run `pnpm run sync-version` (or `pnpm build`) to update.
-export const VERSION = "0.16.2";
+export const VERSION = "0.16.4";
 export const NAME = "passkey-kit";
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "passkey-kit",
-  "version": "0.16.2",
+  "version": "0.16.4",
   "description": "A helper library for creating and using smart wallet accounts on the Stellar blockchain.",
   "author": "Tyler van der Hoeven <tyler@stellar.org>",
   "license": "MIT",
@@ -26,7 +26,8 @@
   "files": [
     "dist",
     "README.md",
-    "LICENCE"
+    "LICENCE",
+    "SECURITY.md"
   ],
   "dependencies": {
     "@openzeppelin/relayer-plugin-channels": "^0.20.0",
@@ -35,7 +36,7 @@
     "base64url": "^3.0.1",
     "buffer": "^6.0.3",
     "sac-sdk": "0.4.4",
-    "passkey-kit-sdk": "0.8.0"
+    "passkey-kit-sdk": "0.8.2"
   },
   "devDependencies": {
     "@types/node": "^24.6.0",
@@ -82,6 +83,6 @@
     "clean": "rm -rf dist packages/passkey-kit-sdk/dist packages/sac-sdk/dist",
     "build:demo": "cd demo && pnpm --ignore-workspace install && pnpm run build",
     "deploy:demo": "npx wrangler pages deploy",
-    "deploy:demo:prod": "npx wrangler pages deploy --branch production"
+    "deploy:demo:prod": "npx wrangler pages deploy --branch main"
   }
 }