VEYNDO
Handbook
docs/app-security.mdView source ↗

English source · 15 min

App isolation and operator setup

This guide records the enforced boundaries of the current app platform. Read it before adding runtimes, stores or credentials. Architecture and Studio describe the same production owners.

Audit fixes

Finding Current owner and protection Regression
B1 table bomb Pinned Apps runtime/, native verified resource adapter: preflight, element/memory limits, pooling, fuel, epochs Rust oversized private table/growth/host-loop tests; app_components
B2 shared app storage apps/records.rs, migrations 101–102: fixed tables, full logical keys, signed RLS, managed unique/reference projections and own-version compatibility app_shared_storage, app_storage_migration, apps, app_schema, tenant_isolation
B3 service ID impersonation apps/approval.rs: exact Rust-canonical approved digest; reserved names include Payments apps, app_surfaces, payment_providers
B4 wrong webhook tenant webhook_scope.rs, auth middleware: route tenant admission, reject conflicting header app_secrets strict non-owner RLS
B5 global slow event lane events.rs: eight lanes, bounded batches, lease fences, retry and replay app_events, services, rust_connectors
B6 event disclosure event_contract.rs, event_projection.rs: family/own scopes plus minimized payloads app_events, Rust projection tests
B7 client-only surface ACL surface_grants.rs: actor/package/context/action-bound five-minute grant apps, app_surfaces, app_assets
B8 input/storage/drafts input_schema.rs, storage.rs, developer/drafts.rs: recursive bounds, database quotas, actor-private CAS autosave apps, app_preview, frontend safety tests

Independent execution and native authority

veyndo/apps owns the pinned veyndo-app-runtime executor. Native crates/apps passes the direct verified resource predicate to both core-Wasm and component constructors and supplies operator namespace configuration. It keeps no duplicate engine. The runtime itself retains all fuel, epoch, memory/table, host-call, snapshot and output bounds. It has no SQL/network/identity or guest WASI authority. The SDK WIT mirror must have exactly the same bytes as the runtime compiler input. Current package rights and authorized snapshots are checked before invocation; returning an outcome does not authorize a write. The existing native cache compiles outside commerce locks and preserves digest checks inside checkout. Actual extraction and tests.

Complete standard admission sequence

Apps model 0.12.0 enforces all standard domain stages before successful complete compilation. Hosts implement required policy decisions, with no approving defaults; there is no optional callback for omitting a standard metadata domain. Native policies still use the original verified reference/public-read predicates and actual current operator keys, currency/content rules and network admission. New package fields require an explicit compiler update. Independent regressions reject invalid metadata in all 19 stages and preserve first-error/callback order. Compilation remains separate from current identity, consent, actual reference ownership, module preparation and transactional effects. Actual extraction checks.

Complete package decoding and publisher authority

Apps model 0.11.0 owns the full strict package wire, original fingerprints and signing message. Native Veyndo reuses that same model. Distribution validation requires the host's current operator-key verification between metadata and individual dependency checks. Native Ed25519, unsigned reserved namespace checks, service digest pins and scoped dependency locks retain their authority. Shared graph rules reject cycles and upgrades that break active dependants. Artwork URL parsing performs no fetch; a provider declaration grants no financial authority. Independent and composed checks.

Shared lifecycle graphs and current authority

Apps model 0.10.0 compiles the original bounded order/quote extension graphs and accepted snapshot projections. Its required native-base/scope/locale policy has no default approvals. Package policies freeze the full admitted version/digest; they do not freeze actor rights. Native auth is checked for each transition. Apps can narrow native processing but cannot replace payment, delivery or buyer acceptance. The native verified transition predicate remains the final admission check; shared compiler, snapshot parsing and SQL/host effects are not covered by that proof. Customer projections expose accepted labels, never graph policies/grants. Actual component checks.

Operator service configuration

Use the shared strict Manifest and manifest::canonical_digest, or the native CLI below, for the original canonical package bytes:

cargo run --bin veyndo -- --app-digest extensions/apps/service-example/manifest.json
python3 scripts/build_app_ui.py service-example --output .run/service-example.html

The UI builder embeds the SDK into one self-contained HTML bundle and emits its SHA-256. Store that bundle on the configured service. Configure the reviewed manifest digest and exact UI path/digest server-side:

{
  "service_example": {
    "url": "https://apps.example.test",
    "uiUrl": "https://apps.example.test",
    "token": "SERVER_SECRET_INJECTED_BY_OPERATOR",
    "approvedDigests": ["RUST_CANONICAL_PACKAGE_SHA256"],
    "uiDigests": {"index.html": "SELF_CONTAINED_HTML_SHA256"}
  }
}

APP_SERVICES is operator-owned. A merchant cannot replace its URL or become that service by choosing its app ID. Exact bundled and frozen historical manifests remain approved for compatibility; altered content requires an explicit pin. Private origins need exact APP_SERVICE_PRIVATE_ORIGINS approval. Ordinary public egress uses HTTPS, blocks private/reserved addresses and mixed DNS answers, pins DNS and rejects redirects. Ambient proxy variables are ignored. A trusted private origin intentionally grants private-network access; it must never be merchant-controlled.

Register Ed25519 public keys in APP_PUBLISHERS as {"publisher":{"key_id":"BASE64_PUBLIC_KEY"}}. Only signatures using registered keys can occupy publisher_app. veyndo --sign-app MANIFEST.json consumes a base64 32-byte seed from stdin and returns the signed manifest and public key. Private seeds do not belong in app packages, environment JSON, logs or Git. A publisher signature does not automatically authorize an operator service or a changed UI bundle.

Credentials and surfaces

Per-shop/app service, incoming webhook and outgoing signature secrets reuse platform AES-GCM encryption. Authenticated associated data binds tenant, app, kind, digest and revision. Rotation uses a current personal team-manager identity, explicit approval and optimistic revision; GET returns metadata only. Once configured, an invalid or stale tenant secret fails closed rather than falling back to a global token. Existing operator bootstrap secrets remain usable only where no tenant secret was configured.

App callback credentials store only hashes, never raw tokens. Keys bind creator, tenant, app, package, scopes and expiry. Current membership is checked on every call; revocation, permission loss or package changes remove authority. Original app capabilities are stored separately from their mapped core rights: products.read cannot imply assets.read, and jobs.read cannot imply jobs.write. Migration 070 leaves legacy app keys without callback capabilities; rotate them with explicit consent before use. Core callbacks project personal data only with separate customers.pii consent. Surface grants are short-lived browser capabilities with an even narrower action/context boundary.

Pinned iframe HTML is limited to 1 MiB, UTF-8 and expected content type. The host first authorizes the surface and returns an /app-ui/{app}/{digest} document path. This path serves only operator-pinned, secret-free static UI code, with no actor context or credentials passed upstream. The document enforces sandbox allow-scripts in its HTTP CSP as well as the iframe attribute, including when opened directly. Its isolated response allows inline bundle code; the credential-bearing Studio keeps its stricter external-build-script policy. srcdoc is not used because it inherits Studio's CSP and prevents the approved guest code from starting. Unpinned or changed bytes fail closed. Document reads have an eight-request process bulkhead, bounded transport and no-store/no-referrer responses. The host sets an opaque script-only sandbox with restrictive CSP and communicates through source/nonce-checked SDK messages. Direct fetch and form submission are blocked. This is not a proof of zero exfiltration from hostile browser code: self-navigation and browser behavior remain a trust boundary. Review sensitive permissions and UI publishers, or prefer host-native views. No popup permission is implemented by default.

Limits and failure behavior

  • Wasm: 1 MiB linear memory, 10,000 table elements, bounded stack, four core instances per component, 64 pooled runtime instances/memories/tables per process. Typed hooks use 100,000 fuel, five 10 ms epochs and 128 read-only host calls.
  • Compile: four admitted blocking compiles/process, 32 fixed deduplication stripes, 128-entry digest-checked LRU cache, 32 KiB source. Five-second response deadline. A timeout cannot cancel the already-running compiler thread; its admission permit stays held until it exits. This is a bounded compiler gate, not OS process isolation.
  • Service calls: eight slots/tenant-app, sixteen/tenant and 64/process, five-second request deadline and 64 KiB bounded JSON input/output; excess gets 429. Tenant and app limits also use PostgreSQL leases across replicas; the process cap is local.
  • App storage: database trigger enforces 100,000 rows and 64 MiB/tenant-app, including relation writes and rollback. Files use existing product asset quotas; file callback is explicitly requested and uploads are limited to 8 MiB. Inline previews ≤256 KiB.
  • Input: depth twelve, 2,048 nodes, 1,000 array entries and bounded strings/properties; closed supplied schemas support nested object/array/number validation.
  • Preview: ten actor-private environments, one-hour access, twenty apps; no live service/provider effects. Expiry denies access; storage cleanup is an operator concern.
  • Jobs: fenced 60-second claims with explicit bounded lifetime, cancellation ACK and uncertain status after lease loss. Retrying requires review of external effects.

A validation failure rolls back the relevant transaction. SQL quotas also cover concurrent writers, unlike client-only checks. External sends remain at least once; no local transaction proves an external effect occurred only once.

Migration and deployment

Run numbered schema migrations with the dedicated provisioner. Migrations 101–102 consolidate managed app data into four fixed shared tables. Drain old Core writers, create and verify a backup, migrate and compare original records/references, then retire only the verified legacy tables before starting the new runtime. The hosted cutover completed on 15 October; other existing installations still require this coordinated maintenance. Follow the exact procedure and evidence.

Migration 058 is retained immutable history: it introduced the earlier physical tables. It is not the current storage architecture or a standalone upgrade plan. Strict serving uses separate restricted tenant/system logins, role-bound signed contexts and startup audits. Managed app installation never creates SQL objects. Migrations 059–070 add delivery fences, quota accounting, grants, drafts, activity, callback keys, encrypted secrets, private previews, multi-relations, recovery and jobs. Migration 070 stores the exact approved app capabilities separately from team rights. Historical callback keys have no implicit grants and must be renewed.

Update independent service receivers for complete batches and new precise event permissions. Rebuild/pin custom UIs. Existing services without new tenant secrets can keep operator bootstrap tokens, but must pin custom package digests. Existing callback keys and configured tenant secrets need explicit review after package changes. Check private Payments/Storyfront deployment separately; public declaration changes do not deploy their private implementation.

Lean proves selected extracted admission decisions. SQL/RLS correctness, encryption integration, Wasmtime, compiler limits, browsers and remote services rely on concrete regressions and trusted infrastructure. No complete-core certification, universal extension compatibility or production-scale guarantee is claimed.

App lifecycle follow-up — 12 October 2026

Network admission is shared by service actions, event deliveries, pinned UI fetches and remote payment adapters: 64 per process, 16 across a tenant, and eight per tenant/app. PostgreSQL resource leases enforce the tenant/app limits across replicas. Rotating app IDs cannot evade the tenant aggregate. Active counters are never discarded during idle-key cleanup. The real app_events regression holds 16 calls across two replicas and app IDs, rejects a seventeenth before the provider receives it, and confirms another tenant can still proceed.

Opaque guest frames additionally bound pending bridge calls to eight, IDs to 100 characters and serialized inputs to 64 KiB. Duplicate pending IDs are not forwarded. Package/context changes remount the frame; old nonce/source windows and late responses cannot act in its replacement. These are bridge/admission bounds, not a proof of CPU isolation for arbitrary browser JavaScript.

Managed record writes acquire the existing shared tenant/app package fence and compare the installed current digest inside their transaction. Package upgrades use the matching exclusive fence. A queued old-contract write returns conflict without changing records/outbox. Generic workflow declarations validate initial states, edges and immutable fields in this same write path; app-specific states remain in the app Manifest, not Commerce domain directories.

The ERP reference adapter is an independent non-root Rust process with app-only forced-RLS receipt tables. It reuses current scoped Core order callbacks and the shared event signature wire contract. Its own durable receipt joins manual and event entry points and preserves uncertain outcomes through restart. See the app-owned implementation and deployment boundary.

Additional action rights

Action.requiredPermissions contains up to eight known team scopes which must all be granted in addition to permission. Public actions cannot declare private additional rights. HTTP/native UI calls, MCP discovery/invocation, AI plans and job enqueue/claim/progress/retry use the same current actor check. App Studio visual recompilation and AI edits preserve these requirements. Service callback credentials retain their own independent scope and consent checks; a powerful service key never grants the calling user additional rights. For example, marketplace order import requires orders.write, payments.manage and customers.pii; orders.write alone cannot import a paid customer snapshot.

Installed settings and permanent integration credentials

App settings require a current personal administrator and the active package digest. Secrets are write-only in the Studio form, encrypted with the existing app-bound secret owner, and omitted from read responses. Reads expose only nonsecret fields, configured-key names, revision and digest. Stale package digests require explicit review/re-entry. PUT rejects undeclared keys, wrong types, foreign tenants, stale revisions and sandbox writes. Private service actions receive a server-owned _appSettings object; input cannot override it. Public actions and native browser views receive none. Values are not sandbox/release/history-restore units.

Permanent integration keys are an explicit option for current personal team.manage sessions. Their scopes remain intersected with current membership, revocation still applies, and integration credentials cannot mint permanent child keys. persistent_key_admissible has exact generated Lean claims and negative mutations; the proof covers that pure two-boolean predicate, not SQL, encryption, UI correctness or a service provider. Real HTTP/PostgreSQL tests cover those implemented admission boundaries.

The workbench guide documents test coverage and limits.

Shared job controls remain trusted host operations

job_history returns internal rows for a trusted host, not a public response. Before disclosure Core retains current package/action/actor checks, removes the internal fingerprint and clears forbidden message/result fields. Job groups are labels only. Cursors resolve inside the selected tenant/app and remain bounded. job_control requires the caller transaction and a mandatory retry-admission hook; current installed action, primary/additional rights and stored input are checked before queued signaling. Errors require rollback, including hook writes. The component never automatically retries an unknown external outcome or creates an authenticated actor. Creator-role locking, callback leases, direct verified completion admission and encrypted evidence remain native.

Required crypto for shared configuration storage

Shared secrets::Crypto requires authenticated seal/open from the trusted host; no default or plaintext fallback is supplied. The native adapter delegates to the existing platform key owner. The original tenant/app/kind/digest/revision binding prevents envelope substitution. The caller owns transaction commit/rollback; rotation and its metadata-only event remain atomic. Incoming webhook verification must use resolve_locked in its original receipt transaction. Personal-session and administrator gates, approved digest, declared kinds/payloads, sandbox exclusion and browser redaction remain native. Neither ciphertext nor plaintext belongs in metadata responses. Checked revision increments reject invalid/exhausted values.

Studio history and staging boundaries

Shared build history returns trusted host rows, including retained prompt metadata; only native minimized design-evidence projection reaches current authorized users. It is not a public serialization contract. Staging requires explicit native approval before the shared row lock/digest check, then mandatory current private environment/compiler/actor/installer admission. Stage state updates only after installation succeeds in the same caller transaction; every rejection requires rollback. Archive/restore changes development snapshots, never installed packages or records. Archived tenant/app/version identities remain immutable. Original serialized development digest semantics are preserved separately from installed package canonical fingerprints. Mutable draft identity derivation remains native; scoped persistence now uses pinned Apps 0.20.0.

Shared private autosave boundary

drafts::Owner is an already admitted tenant/actor scope, never an authentication credential supplied by a browser. Native middleware retains current developer rights, signed SQL scope and the existing personal identity or integration-token binding. Shared save requires same-connection environment ownership admission with no approving default. Original actor advisory lock, row revision and quota checks remain in the caller transaction. Reads and deletes include both tenant and actor. Strict wire decoding permits unfinished editor work; it is not approval for installation or business effects. No schema creation, version/package mutation or outbox effect occurs. Boundary regression.

Historical record access and shared restoration

Apps 0.21.0 retains the original list-action rights with each immutable snapshot. ReadAuthority evaluates them against the host's current authenticated principal; malformed stored scope values fail closed. Native current entity rights still apply before lookup, and only current declared fields reach the response. Trusted history rows must never be serialized directly as public output.

RestoreHost must use the normal current-package/field/reference/lifecycle/CAS writer on the same transaction. Native explicit review, expected revision, signed scope, actor/source and actual save remain attached. Failed admission or history/audit/event persistence requires caller rollback. Capturing the same version cannot replace its fields, rights or attribution. Original retention is scoped to the tenant/app and record. Regressions and boundary.

Shared activation authority

activation::StateHooks requires actual host configuration, activation and connected-frontend admission, with no approving defaults. Native Veyndo retains current management/merchant scope, current package/actor rights, consent/operator trust, signed dependencies and commerce/native lifecycle checks. Input flags do not grant those authorities. Configuration locks precede shared tenant/app fences, which also exclude the actual installer and active-package writer. Deactivation checks active dependants after connected frontend admission. Revision CAS remains last, preserving original first-error semantics. Any host, dependency, CAS or SQL failure requires rollback. The operation deletes no app data and emits no new state event. Regression boundary.

Shared schema migration authority

schema_upgrade::Validation is required for every converted record on the original installation transaction. Native Veyndo calls data::fields and native_data::validate_languages, in that order, then checks revision exhaustion. Complete installation retains current actor, package compiler, consent, publisher trust, actual references/projections and tenant/package fences. Any migration, validation, snapshot or later installation error requires caller rollback. Recovery snapshots include old declared fields only and remain tenant/app scoped; there is no public raw-history endpoint or implicit historical restore writer. Independent fixtures exercise conversion/policy/late-hook denial, actual byte/row budgets, collision and overflow. Native API fixtures additionally exercise disabled languages and exhausted revisions without package/record/history/outbox changes. Schema recovery evidence.

Independent runtime network boundary

The Apps runtime service is a separate composition root, not HTTP/network access inside the guest engine or storage library. Its fixed authenticated introspection endpoint supplies current subject/tenant/scope/audience/expiry for each protected request. No request tenant, permission or source field grants access; there is no cache, issuer or parallel user/role store. Identity redirects, failures and oversized responses reject with sanitized errors. Origin and duplicate authorization checks apply before dispatch. HTTP/MCP use the same strict typed operation and no-store responses. Supplied snapshot IDs never read live records.

Task-owned global/tenant/subject permits survive requester cancellation; Wasmtime retains its original import, memory/table, fuel/epoch, ABI and output bounds. The result states simulation/no effect. No SQL, live resolver or financial writer is added. This service can use an external identity owner independently; connecting native sessions and a complete app-data/installation host remains separate work. Runtime service acceptance.

Independent App job supervision

The optional job supervisor exposes existing job history/detail and approved cancel/retry/resolve/archive through HTTP, MCP and SDK. Shared projection/event ownership preserves current rights, package binding and original control/lease/CAS semantics in Veyndo. The schema-5 serving login cannot create jobs or change worker input/results; execution retains its actual producer/consumer owner. Acceptance.

Independent portable package installation

The explicit App installation profile uses Apps 0.28.0 / Data service 0.4.0 for package review/install through HTTP, MCP and the unchanged SDK. The full compiler and original installer/model sequence retain exact approval, immutable versions, current personal/live authority and fixed-table row/byte budgets. Native model installation supplies its actual compatibility policy to the same owner. Independent and native acceptance.

Independent installation settings

The optional App settings profile provides HTTP, MCP and JavaScript access to declared configuration. It shares native encrypted partial updates, package/revision fences and secret-safe projection, with explicit personal live administrator admission. The serving role cannot install packages or create schema objects. Reader/write profiles retain their separate grants. The original vault envelope is shared; existing native ciphertext stays readable.