Tutorials

All 94 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 gap at 61 — retired during a connector refactor, never reused. See Detect tampering and Choose a signature provider for guides built directly on several of these.

Run any of them directly: node_modules/.bin/tsx examples/tutorials/<NN-name>/run.ts.

Fundamentals (01-24)

#	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
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
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
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
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

Execution authorization and envelope (25-34)

#	Name	Demonstrates
25	Execution Permit Generation	The @parmana/execution-control ExecutionPermit model, see @parmana/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
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

Gateway hardening: mutate, verify, watch it fail (35-46)

The same pattern each time: generate something valid, mutate exactly one thing, re-verify, confirm rejection. See 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

Cryptography (47-52)

#	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
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

Execution Permit and Receipt: a separate, unwired path (53-56)

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 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

Credential isolation (57-60)

#	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
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

Signal/Intent binding (62)

Tutorial 61 does not exist — the number was retired during a connector refactor (an earlier, single Razorpay tutorial split into the Razorpay group below) and was never reused.

#	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 Trust and Claims for the live bypass this closed

Razorpay: connector, fetch-verification, caps, webhooks, settlement (63-68)

See Razorpay for the connector these exercise and its exact proven scope.

#	Name	Demonstrates
63	Razorpay Refund Connector	The full path from a BusinessTransaction through policy to a real (mocked) refund call, via the same production composition (createExecutionSystem + createApplication) server.ts itself calls
64	Razorpay Policy Denial	A refund exceeding the payment’s real refundable remainder rejected, zero refund calls ever reaching the connector
65	Razorpay Signal-State Verification	RazorpaySignalStateVerifier independently fetching the real payment and rejecting a caller-declared signal that disagrees with it, naming the exact mismatch
66	Razorpay Daily Cumulative Cap	Two concurrent refunds racing the daily cap; the atomic RazorpayDailyRefundLedger lets exactly one through, never both
67	Razorpay Webhook Receipt	HMAC-SHA256 signature verification over the raw body plus atomic eventId dedupe, exercised directly against the real functions
68	Razorpay Settlement Confirmation	RazorpaySettlementProcessor always re-fetching the refund from Razorpay rather than trusting the webhook’s own claimed event type

HubSpot: connector, denial, verification, approval artifacts (69-72)

See 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

Refusal records and signed audit events (73-75)

#	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

Caller scoping and concurrency (76-78)

#	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

Storage and config validation (79-80)

#	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

Multi-connector composition (81-83)

#	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 Razorpay and HubSpot verifiers into the one verifier RuntimeEngine accepts, with no cross-contamination between them
83	Capability/Policy Binding (TD-22)	CapabilityPolicyBinder closing the gap where a real, fund-moving capability could be paired with the wrong, unprotected policy

HTTP surface hardening (84, 88-91)

#	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 $refs
91	Graceful Shutdown	The SIGTERM/SIGINT handler draining in-flight requests before exit, force-exiting on a hung close after a bounded timeout

Real-world fixtures and gateway internals (85-87, 92-93)

#	Name	Demonstrates
85	Razorpay Real Webhook Fixture	The actual POST /webhooks/razorpay route replaying a real, PII-redacted Razorpay-delivered payload, not a synthetic one this codebase constructed
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

SDK and generic verification (94-95)

#	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

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 — see docs/VERIFICATION-GAPS.md G-27.)

Next

Detect tampering

Three of the tutorials above, run live with real output.

Trust and Claims

How every claim on this site, including every line above, maps back to code and tests.