> ## Documentation Index
> Fetch the complete documentation index at: https://docs.parmanasystems.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Tutorials
> Numbered examples in examples/tutorials/, grouped by what they demonstrate. This page links to them, it does not duplicate their content.
**\[AVAILABLE]**, 93 run unattended in CI via `npm run examples`
(`scripts/run-examples.ts`), confirmed passing this pass; one (09, noted
below) needs a live server and runs individually. Numbering has a few
intentional gaps (61, 63-68, 85), retired when the Razorpay connector was
deliberately removed from the codebase, never reused, see the note below. See
[Detect tampering](/guides/detect-tampering) and [Choose a signature
provider](/guides/choose-a-signature-provider) for guides built directly on
several of these.
Run any of them directly: `node_modules/.bin/tsx examples/tutorials//run.ts`.
| # | Name | Demonstrates |
| -- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| 01 | Hello World | Constructing a `BusinessTransaction`, no execution yet |
| 02 | Policy Evaluation | `PolicyEngine.evaluate()` in isolation |
| 03 | Runtime Execution | First full `RuntimeFactory` execution, using the `DefaultExecutionSystem` placeholder |
| 04 | Policy Router | Resolving a `PolicyReference` to a loaded policy |
| 05 | Verification | Fresh verification appended to a trust record's history |
| 06 | Replay | `@parmana/replay`'s real, scoped policy re-evaluation, see [Replay](/replay/overview) |
| 07 | Receipt Generation | The real, wired `Receipt` (via `@parmana/crypto`'s `ReceiptCrypto`), not `@parmana/receipt`'s separate model |
| 08 | Human Approval | An `Authority` / `Authorization` / `Intent` chain without executing |
| 09 | REST API | `POST /transactions` over HTTP, excluded from the unattended batch, needs a live server, see [REST API Introduction](/api-reference/introduction) |
| 10 | End-to-End | Execute, verify, and receipt in one run, still via `DefaultExecutionSystem` |
| 11 | Execution Authorization | The `SignedExecutionAuthorization` envelope itself, printed directly, see [Authorize and execute end to end](/guides/authorize-and-execute) |
| 12 | Envelope Verification | `EnvelopeVerifier`'s per-check breakdown on a valid envelope |
| 13 | Post-Quantum Signatures | `config.crypto.primarySignatureProvider` read and printed |
| 14 | Custom Policy | Writing and evaluating a policy outside the shipped `vendor-payment` one, see [Write your first policy](/guides/write-your-first-policy) |
| 15 | Custom Runtime Component | Extending `RuntimePipeline` with a custom `RuntimeComponent` |
| 16 | Runtime Pipeline | The pipeline's stage composition, inspected directly |
| 17 | Multi-Policy Routing | Routing different transactions to different policies |
| 18 | Runtime Hooks | `RuntimeHook` / `RuntimeHookRunner` lifecycle callbacks |
| 19 | Runtime Composition | Assembling a `Runtime` from individual components |
| 20 | Batch Execution | Multiple transactions through one runtime instance |
| 21 | Partial Failure Handling | One transaction in a batch failing without stopping the rest |
| 22 | Idempotent Execution | Resubmitting the same `businessTransactionId` |
| 23 | Production Deployment | Configuration shape for a non-local deployment |
| 24 | SDK Integration Patterns | Common client-side call patterns |
| # | Name | Demonstrates |
| -- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| 25 | Execution Permit Generation | The `@parmana/execution-control` `ExecutionPermit` model, see [@parmana/receipt](/reference/receipt) for its real, separate scope |
| 26 | Execution Authorization Verification | `AuthorizationVerifier` checking a signature independent of the fuller envelope flow |
| 27 | Authorization Expiration | An expired `expiresAt` rejected by `EnvelopeVerifier` |
| 28 | Envelope Replay Detection | A reused nonce rejected on the second check |
| 29 | Authorization Tampering | A mutated payload failing signature verification, per-check breakdown, see [Detect tampering](/guides/detect-tampering) |
| 30 | Policy Version Pinning | An authorization bound to one exact `policyVersion` |
| 31 | Authorization Binding | `authorizationId` binding an authorization to one decision |
| 32 | Execution Pipeline | The stages between decision and release, inspected directly |
| 33 | Execution Boundary | Where policy evaluation ends and release begins |
| 34 | Execution Gateway | `ExecutionGateway` constructed and exercised directly, see [The gateway](/concepts/the-gateway) |
The same pattern each time: generate something valid, mutate exactly one thing, re-verify,
confirm rejection. See [Detect tampering](/guides/detect-tampering) for three of these run
live with real output.
| # | Name | What's mutated |
| -- | --------------------- | ------------------------------------------------------- |
| 35 | Replay Attack | The same authorization submitted twice |
| 36 | Parameter Tampering | A parameter inside the executable content |
| 37 | Action Substitution | The `action` field |
| 38 | Target Substitution | The `target` field |
| 39 | Policy Substitution | The referenced policy |
| 40 | Signature Forgery | The signature itself, signed by a different key |
| 41 | Expired Authorization | The clock, past `expiresAt` |
| 42 | Nonce Reuse | The nonce, submitted a second time |
| 43 | Stolen Authorization | A valid envelope replayed by a different party |
| 44 | Direct API Bypass | Attempting to skip the gateway entirely |
| 45 | Connector Bypass | Attempting to reach a connector without a valid session |
| 46 | TOCTOU Protection | The full check-vs-use gap, end to end |
| # | Name | Demonstrates |
| -- | --------------------- | ------------------------------------------------------------------------------------------------------------------- |
| 47 | Canonical JSON | `CanonicalSerializer`'s key-sorted, deterministic output |
| 48 | Deterministic Hashing | The same content hashing identically every time |
| 49 | Detached Signatures | Signing content without embedding it in the signature artifact |
| 50 | Ed25519 | Default signature provider, sign and verify, see [Choose a signature provider](/guides/choose-a-signature-provider) |
| 51 | Dilithium3 | ML-DSA-65 (post-quantum), signing with the `pq` key, same guide |
| 52 | Hybrid Signatures | Both algorithms signing the same artifact at once, same guide |
None of these four reach `packages/api` or `packages/runtime`. They exercise
`@parmana/execution-control`'s `ExecutionPermit` and `@parmana/receipt`'s
`ExecutionReceipt`, real and tested, disconnected from the default server. See
[@parmana/receipt](/reference/receipt) for the precise scope note.
| # | Name | Demonstrates |
| -- | ------------------------------ | -------------------------------------------------------------------------- |
| 53 | Execution Permit | Building an `ExecutionPermit` with `ExecutionPermitBuilder` |
| 54 | Execution Receipt | `ExecutionReceiptBuilder.build(permit, trustRecord)` |
| 55 | Execution Receipt Verification | `ExecutionReceiptVerifier.verify()`, a structural check, not cryptographic |
| 56 | Complete Execution Flow | Permit through receipt through verification, one run |
| # | Name | Demonstrates |
| -- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| 57 | Credential Isolation | The concept end to end, at the library level |
| 58 | Session Credentials | Issue, consume, expire, reuse-reject, revoke, see [Issue and verify session credentials](/guides/session-credentials) |
| 59 | Secure Connectors | Gateway attestation plus a `SessionCredentialSecureConnector`, including a spoofed-attestation rejection |
| 60 | End-to-End Enterprise Execution | The full credential-isolated path, one run |
Tutorials 61, 63-68, and 85 don't exist. All were retired when the Razorpay
connector was deliberately removed from the codebase (`docs/CLAIMS.md`'s "Key
Compromise Notice" section and the connector-removal history), never reused.
`examples/README.md` in the source repository is the authoritative, current
tutorial list.
| # | Name | Demonstrates |
| -- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 62 | Signal/Intent Binding | `SignalIntentBinder` rejecting a caller-declared signal that doesn't match `intent`, and the same transaction approved once correctly bound. See [Security](/security/overview) for the live bypass this closed. |
See [HubSpot](/integrations/hubspot) for the connector these exercise and its exact proven
scope.
| # | Name | Demonstrates |
| -- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 69 | HubSpot Deal Update Connector | The full path from a `BusinessTransaction` through policy to a real (mocked) `PATCH` call, via the same production composition `server.ts` itself calls |
| 70 | HubSpot Policy Denial | A move out of a terminal pipeline stage rejected, the deal left completely untouched on HubSpot |
| 71 | HubSpot Signal-State Verification | `HubSpotSignalStateVerifier` independently fetching the real deal and rejecting a caller-declared `currentDealStage` that disagrees with it |
| 72 | HubSpot Approval Artifact | An over-threshold amount change requiring a real, independently-issued, signed Approval Artifact scoped to the right deal and amount, not a bare `preAuthorizedForAmountChange: true` claim |
| # | Name | Demonstrates |
| -- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| 73 | Refusal Records | A policy `REJECT` producing a durable, signed Refusal Record, retrievable and independently verifiable afterward |
| 74 | Refusal Record Fail-Open | A Refusal Record write failure never blocking, delaying, or changing the actual rejection a caller receives; the record is evidence, not a gate |
| 75 | Signed Audit Events | Caller-authentication audit events signed with the same root of trust as every other Parmana artifact, tampering detectable |
| # | Name | Demonstrates |
| -- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| 76 | Caller Principal Scoping | `isPrincipalAllowed()`: fail-closed by default, an authenticated caller may only assert its own identity absent an explicit operator grant |
| 77 | Caller Ownership Scoping | `isOwnedByCaller()`: one authenticated caller can't read another caller's transaction, trust record, or receipt history |
| 78 | Duplicate Transaction Race | Two concurrent `create()` calls for the identical `businessTransactionId`, exactly one winning, the stored record never silently overwritten |
| # | Name | Demonstrates |
| -- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| 79 | Storage Backend Selection | `StorageFactory.createFromEnvironment()`, and why `NODE_ENV=test` always resolves to in-memory regardless of other config |
| 80 | Fail-Closed Config Validation | Invalid `CRYPTO_MODE`/`PARMANA_STORAGE`/`PARMANA_API_KEYS` values rejected at load time with a named, specific error, never a silent fallback |
| # | Name | Demonstrates |
| -- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 81 | Connector Execution Gateway | `GatewayConnectorRegistry` resolving a capability string to its registered connector, each connector failing closed independently when its own credentials are absent |
| 82 | Composite Signal-State Verification | `CompositeSignalStateVerifier` composing the real `HubSpotSignalStateVerifier` with a second, illustrative hand-written verifier into the one verifier `RuntimeEngine` accepts, with no cross-contamination between them |
| 83 | Capability/Policy Binding | `CapabilityPolicyBinder` closing the gap where a real, fund-moving capability could be paired with the wrong, unprotected policy |
| # | Name | Demonstrates |
| -- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 84 | Caller Authentication | The real Express caller-authentication middleware over a real listening server: valid/missing/invalid credentials, per-caller scoping, key rotation and revocation |
| 88 | Malformed Request Handling | Malformed JSON and oversized request bodies returning specific `400`/`413` errors, not a generic `500` |
| 89 | Readiness Probe | `GET /ready`, distinct from `GET /health`, across memory-backed and (genuinely unreachable) Supabase-backed storage |
| 90 | OpenAPI Self-Description | `GET /openapi.yaml` serving a valid, unauthenticated, fully-dereferenced OpenAPI 3.1 document, no unresolved `$ref`s |
| 91 | Graceful Shutdown | The `SIGTERM`/`SIGINT` handler draining in-flight requests before exit, force-exiting on a hung close after a bounded timeout |
| # | Name | Demonstrates |
| -- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 86 | Gateway Attestation | `SignedTokenConnectorAuthenticator`'s full surface: payload tampering, the missing-attestation default, request-bound vs. signature-only checks, the trusted-connector allow-list |
| 87 | Key Provider Path Traversal | `FileKeyProvider` rejecting a path-traversal `keyId` on every one of its four methods, before ever touching the filesystem |
| 92 | Public API Boundary | `@parmana/execution-gateway`'s internal implementation classes checked directly against the real compiled export surface, none reachable from outside |
| 93 | Trust Record Ordering | A Trust Record's collections preserving insertion order through a full round trip, hash and signature both still valid on reload |
| # | Name | Demonstrates |
| -- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 94 | SDK HTTP Transport | The published TypeScript SDK's `HttpTransport`: bearer-key attachment and its full status-code-to-typed-error-class mapping, including `403`/`POLICY_DENIED` |
| 95 | Generic Approval Verifier | `ApprovalVerifier` exercised directly, connector-agnostic, with its full nine-check breakdown and durable, cross-process replay protection |
Tutorials 96 through 104 exist and pass in CI but aren't yet in the tables
above.
**105: Tenant Key Isolation.** Demonstrates the per-tenant signing-key fix: a transaction
with a provisioned `tenant.` key signs and verifies only under that key, an
unprovisioned tenantId falls back silently to the shared default key, and a transaction with
no tenantId is unaffected. Newly added to `scripts/run-examples.ts`'s list: it existed and
worked standalone since its own commit, but `npm run examples` never exercised it until now.
**106: API Key Issuance (Writing a New Policy).** A brand-new `policies/api-key-issuance/1.0.0`
policy and worked example showing how to author a policy correctly under the fail-closed
`boundSignals` discipline and zero-conflict shape from the start, rather than retrofitting it
afterward the way all 10 pre-existing policies needed. Also in `scripts/run-examples.ts`'s
list from its first commit.
**107: Offline Verification.** `verifyExecutionTrustRecordOffline` verifying a genuine
record, a tampered one, and a wrong-key attempt, with zero disk/network/env-var access. One
level stronger than [Verify a trust record independently](/guides/verify-independently)'s
"server process stopped" proof.
**108: Public-Key Discovery.** `GET /keys/:keyId` and `GET /.well-known/jwks.json`,
unauthenticated, plus the full chain: a key fetched over real HTTP verifies a real record
fully offline via Tutorial 107's function, with zero further server calls.
**109: Durable-Evidence Key Rotation.** `PARMANA_VERIFICATION_KEY_ID` rotating the Trust
Record/Refusal Record/Audit Event signing key to a freshly generated keyId without
invalidating any already-issued signature. That property was previously false (the only
prior "rotation" was overwriting the key file in place).
**110: Hybrid-Signature Downgrade Protection.** The opt-in `HYBRID_SIGNATURE_REQUIRED` flag
closing the gap where a hybrid-signed record's ML-DSA-65 signature could be silently stripped
with no cryptographic trace, while leaving every already-issued record (default policy,
unaffected) exactly as verifiable as before.
## Scenarios
Two production-shaped scenarios also live in `examples/scenarios/`, run manually via `npm
run examples` (`scripts/run-examples.ts`), not currently part of CI: `expense-approval`,
`purchase-order`. (A third, `vendor-payment`, existed here until `payments:execute` was
removed from the repository entirely.)
## Next
Three of the tutorials above, run live with real output.
What's tested, what's an honest gap, and how to verify any claim yourself.