@enc-protocol/app-sdk-base 0.9.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Zhenyu Sun, Tomoya Nagasawa, and WEAVEDB LTD.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,125 @@
+# @enc-protocol/app-sdk-base
+
+Platform-agnostic base SDK for per-app ENC protocol clients. Provides the AppSdk class that every per-app SDK extends, with AppClient multi-enclave coordination, plugin registry wiring, and cross-enclave read views.
+
+## Install
+
+```bash
+npm install @enc-protocol/app-sdk-base
+```
+
+## API
+
+### AppSdk (main export)
+
+**`new AppSdk(opts)`** — Initialize the app SDK.
+- `opts.manifests` (required): `{ app, schema, infra?, enclaves: {...} }`
+- `opts.adapter`: Single shared adapter (shorthand for single-enclave apps)
+- `opts.adapters`: Map of `{ EncleaveName: adapter }` for multi-enclave apps
+- `opts.plugins`: ClientPluginRegistry instance (defaults to `defaultClientPluginRegistry()`)
+
+Resolves data_types and read views to enclave events via `schema.tableMap`, dispatching to the appropriate enclave's adapter.
+
+**`await appSdk.init()`** → `this` — Initialize the SDK. Currently a no-op; reserved for future async setup.
+
+**`await appSdk.submit(name, args)`** → result — Submit a write event. `name` may be a data_type or enclave event; resolved and routed to the owning enclave's adapter.
+
+**`await appSdk.query(name)`** → rows — Query a read view or enclave event. Cross-enclave reads route to the DataView; single-enclave queries dispatch to the adapter.
+
+**`whoami()`** → `{ appId, pubHex, schemaName, dataTypes, reads, enclaves }` — Introspection: app identity, schema name, declared data types and reads, and enclave roster.
+
+**`raw()`** → AppClient — Access the underlying AppClient for primitive operations.
+
+### AppClient
+
+**`new AppClient(opts)`** — Initialize the multi-enclave coordinator.
+- `opts.manifests` (required): `{ app, schema, infra?, enclaves: {...} }`
+- `opts.adapter` or `opts.adapters`: Adapter(s) for each enclave
+- `opts.identity`: Optional `{ pubHex }` identity
+- `opts.plugins`: ClientPluginRegistry (defaults to `defaultClientPluginRegistry()`)
+
+**`await appClient.init()`** → `this` — Symmetry hook; currently a no-op.
+
+**`await appClient.submit(enclaveName, event, args)`** → result — Submit to a specific enclave. Automatically ingests into DataView if cross-enclave reads are configured.
+
+**`await appClient.query(enclaveName, event, opts)`** → result — Query a specific enclave event.
+
+**`await appClient.grant(enclaveName, target, role)`** → result — Grant a role to a target.
+
+**`await appClient.revoke(enclaveName, target, role)`** → result — Revoke a role.
+
+**`await appClient.move(enclaveName, target, from, to)`** → result — Move a target between states.
+
+**`await appClient.transfer(enclaveName, target, trait)`** → result — Transfer a trait.
+
+**`await appClient.queryMembers(enclaveName)`** → array — List enclave members (if adapter supports it).
+
+**`whoami()`** → `{ appId, pubHex, enclaves: [...] }` — Introspection: app and enclave identity.
+
+### DataView
+
+**`new DataView(crossReads, opts)`** — Initialize cross-enclave read view storage.
+- `crossReads`: Object mapping view names to `{ from, via, key, access }` (from `infra.json`'s `cross_enclave_reads`)
+- `opts.ingestFn`: IngestStrategyFn override (default: plugin-client-base/ingest)
+- `opts.initStorageFn`: Storage initialization override
+
+**`dataview.query(viewName)`** → array | null — Query a cross-enclave read. Returns rows in reverse chronological order (append-only) or as a Map snapshot (for UPSERT views).
+
+**`dataview.ingest(enclaveName, event)`** — Internal: ingest an event from a watched enclave. Delegates to the IngestStrategyFn plugin.
+
+**`dataview.watchedEnclaves()`** → Set — Return the set of source enclaves this view consumes.
+
+**`dataview.has(viewName)`** → boolean — Check if a view is configured.
+
+**`dataViewFromInfra(infraManifest, opts)`** → DataView — Factory: build a DataView from an infra manifest.
+
+### Plugin Registry & Encryption
+
+**`defaultClientPluginRegistry()`** → ClientPluginRegistry — Create a registry pre-bound with protocol-level client slots from `@enc-protocol/plugin-client-base`.
+
+**`await registerDmRatchetEncryption(plugins, { getEpochSecret })`** → plugins — Wire the ENC protocol's Ratchet_DM encryption (secp256k1 + HKDF-SHA256 + XChaCha20-Poly1305) into a ClientPluginRegistry. Replaces the pass-through EnvelopeEncryptFn/DecryptFn defaults. Lazy-imports `@enc-protocol/plugin-dm-ratchet`.
+
+### Protected Methods (for subclass overrides)
+
+**`await sdk._encrypt(dataType, args, opts)`** → args — Envelope-encrypt hook. Default: pass-through via EnvelopeEncryptFn plugin. Subclasses override for real encryption.
+
+**`await sdk._decrypt(eventType, content, fromPub)`** → content — Envelope-decrypt hook. Pairs with `_encrypt`. Default: pass-through.
+
+## Example
+
+```javascript
+import { AppSdk, defaultClientPluginRegistry } from '@enc-protocol/app-sdk-base'
+
+// Load manifests (typically baked into per-app SDK)
+const manifests = {
+  app: { id: 'hello', enclaves: ['Hello'] },
+  schema: { name: 'HelloSchema', data_types: {...}, reads: {...}, tableMap: {...} },
+  enclaves: {
+    Hello: { manifest: {...} }
+  }
+}
+
+// Create adapter (e.g., relay, local enclave simulation, etc.)
+const adapter = {
+  submit: async (event, args) => ({ id: '123', ...args }),
+  query: async (event, opts) => []
+}
+
+// Initialize and use
+const sdk = new AppSdk({
+  manifests,
+  adapter,
+  plugins: defaultClientPluginRegistry()
+})
+
+await sdk.init()
+
+// Submit a write
+const result = await sdk.submit('message', { text: 'Hello' })
+
+// Query a read
+const rows = await sdk.query('messages')
+
+// Introspect
+console.log(sdk.whoami())
+// { appId: 'hello', pubHex: null, schemaName: 'HelloSchema', dataTypes: [...], reads: [...], ... }

package/app-client.mjs

@@ -0,0 +1,179 @@
+/**
+ * AppClient — multi-enclave coordinator for an enc-protocol app.
+ *
+ * Platform-agnostic. Caller supplies pre-loaded manifests + one adapter
+ * per enclave. No fs reads, no mode switch, no state persistence — those
+ * are platform concerns (the host layer; the web shell).
+ *
+ *   new AppClient({
+ *     manifests: { app, schema, infra?, enclaves: { Hello: {...} } },
+ *     adapters:  { Hello: helloAdapter },
+ *     identity?: { pubHex },
+ *   })
+ *
+ * Backward-compat shorthand: single-enclave apps may pass `adapter`
+ * instead of `adapters`; it's mapped to the app's sole enclave.
+ *
+ * Every adapter must implement: submit(event, args) → result.
+ * Optional: query, grant, revoke, move, transfer, queryMembers,
+ * createEnclave. AppClient calls them when the corresponding method is
+ * invoked.
+ */
+
+import { DataView, dataViewFromInfra } from './dataview.mjs'
+import { ClientPluginRegistry } from '@enc-protocol/plugin-runtime'
+import { defaultClientBindings } from '@enc-protocol/plugin-client-base'
+
+/**
+ * Build the default ClientPluginRegistry pre-bound with every
+ * protocol-level client slot from @enc-protocol/plugin-client-base.
+ * Callers can pass their own registry to override individual slots
+ * (e.g. swap EnvelopeEncryptFn for a real MLS impl).
+ */
+export function defaultClientPluginRegistry() {
+  return new ClientPluginRegistry({ bindings: defaultClientBindings })
+}
+
+export class AppClient {
+  /**
+   * @param {object} opts
+   * @param {object} opts.manifests
+   * @param {object} [opts.adapter]
+   * @param {object} [opts.adapters]
+   * @param {object} [opts.identity]
+   * @param {ClientPluginRegistry} [opts.plugins]  defaults to defaultClientPluginRegistry()
+   */
+  constructor(opts = {}) {
+    const { manifests, adapter, adapters, identity, plugins } = opts
+    this.plugins = plugins || defaultClientPluginRegistry()
+    if (!manifests?.app) throw new Error('AppClient: manifests.app required')
+    if (!manifests?.schema) throw new Error('AppClient: manifests.schema required')
+    if (!manifests?.enclaves) throw new Error('AppClient: manifests.enclaves required')
+
+    this.manifests = manifests
+    this.app = manifests.app
+    this.schema = manifests.schema
+    this.appId = this.app.id || this.app.appId
+    this.identity = identity || null
+
+    const declared = this.app.enclaves || []
+    if (!declared.length) throw new Error(`AppClient: app "${this.appId}" declares no enclaves`)
+
+    // Normalize adapters to a map. Three resolution paths in priority:
+    //   1. `adapters: { Timeline: a, Personal: b }` — explicit per-enclave
+    //   2. `adapter: a` — single shared adapter for every declared enclave
+    //   3. TransportFn plugin from the registry — `(opts) → adapter | adapters-map`
+    //
+    // The TransportFn fallback lets an app register an alternative
+    // transport (relay, libp2p, future MLS-native transport) without
+    // changing AppClient call sites.
+    const adapterMap = adapters ? { ...adapters } : {}
+    if (adapter && !adapters) {
+      for (const name of declared) adapterMap[name] = adapter
+    }
+    if (!adapter && !adapters && this.plugins.has('TransportFn')) {
+      const produced = this.plugins.invoke('TransportFn', opts)
+      if (produced && typeof produced === 'object' && !produced.submit) {
+        // produced is a map { Enclave: adapter, ... }
+        for (const [n, a] of Object.entries(produced)) adapterMap[n] = a
+      } else if (produced && typeof produced.submit === 'function') {
+        for (const name of declared) adapterMap[name] = produced
+      }
+    }
+
+    /** @type {Map<string, {adapter, manifest}>} */
+    this.enclaves = new Map()
+    for (const name of declared) {
+      const ad = adapterMap[name]
+      if (!ad) {
+        throw new Error(
+          `AppClient: no adapter supplied for enclave "${name}" ` +
+          `(app "${this.appId}" declares ${declared.length} enclaves; ` +
+          `pass via { adapter } for a shared adapter, or ` +
+          `{ adapters: { ${declared.map(n => `${n}: ... ` ).join(', ')} } } for per-enclave)`,
+        )
+      }
+      const enclaveManifest = manifests.enclaves[name]
+      if (!enclaveManifest) {
+        throw new Error(`AppClient: manifests.enclaves.${name} missing`)
+      }
+      this.enclaves.set(name, { adapter: ad, manifest: enclaveManifest })
+    }
+
+    // DataView consumes the IngestStrategyFn plugin from the registry.
+    // Default impl is identical to the previous inline behavior; apps
+    // can swap in a CRDT-aware ingest by registering their own.
+    this.dataview = dataViewFromInfra(manifests.infra, {
+      ingestFn: this.plugins.get('IngestStrategyFn') || undefined,
+    })
+  }
+
+  /**
+   * Init is a no-op now (no fs work). Kept for API symmetry — callers
+   * still await it and can rely on it returning `this`. Reserved for
+   * future async setup (e.g. registry lookups).
+   */
+  async init() { return this }
+
+  _enclave(name) {
+    const e = this.enclaves.get(name)
+    if (!e) throw new Error(`AppClient: enclave "${name}" not registered`)
+    return e
+  }
+
+  // ── Per-enclave protocol ops ────────────────────────────────────────
+
+  async submit(enclaveName, event, args = {}) {
+    const e = this._enclave(enclaveName)
+    const r = await e.adapter.submit(event, args)
+    if (this.dataview && !r?.error) {
+      this.dataview.ingest(enclaveName, {
+        type: event,
+        content: args,
+        parsed: args,
+        from: this.identity?.pubHex || e.adapter.pubHex || e.adapter.identity?.pubHex || '',
+        timestamp: Date.now(),
+        id: r?.id || '',
+      })
+    }
+    return r
+  }
+
+  async query(enclaveName, event, opts) {
+    return this._enclave(enclaveName).adapter.query(event, opts)
+  }
+
+  async grant(enclaveName, target, role) {
+    return this._enclave(enclaveName).adapter.grant(target, role)
+  }
+
+  async revoke(enclaveName, target, role) {
+    return this._enclave(enclaveName).adapter.revoke(target, role)
+  }
+
+  async move(enclaveName, target, from, to) {
+    return this._enclave(enclaveName).adapter.move(target, from, to)
+  }
+
+  async transfer(enclaveName, target, trait) {
+    return this._enclave(enclaveName).adapter.transfer(target, trait)
+  }
+
+  async queryMembers(enclaveName) {
+    const a = this._enclave(enclaveName).adapter
+    return typeof a.queryMembers === 'function' ? a.queryMembers() : []
+  }
+
+  // ── Introspection ───────────────────────────────────────────────────
+
+  whoami() {
+    return {
+      appId: this.appId,
+      pubHex: this.identity?.pubHex || null,
+      enclaves: [...this.enclaves.entries()].map(([name, e]) => ({
+        name,
+        enclaveId: e.adapter.enclaveId || null,
+      })),
+    }
+  }
+}

package/app-sdk.mjs

@@ -0,0 +1,302 @@
+/**
+ * AppSdk — app-driven SDK for an enc-protocol app.
+ *
+ * Platform-agnostic. Caller supplies pre-loaded manifests + adapter(s);
+ * AppSdk adds app-level submit/query that resolve via the app's
+ * schema.tableMap to enclave events.
+ *
+ *   new AppSdk({
+ *     manifests: { app, schema, infra?, enclaves: { Hello } },
+ *     adapter:  helloAdapter,             // single-enclave shorthand
+ *     adapters: { Hello: helloAdapter },  // multi-enclave
+ *   })
+ *
+ * No fs reads, no Node-specific imports. Generated per-app SDKs
+ * (HelloSdk, DmSdk, ...) extend this class with typed methods and bake
+ * their manifests in — so callers just construct with `{ adapter }`.
+ *
+ * For multi-enclave apps the resolver looks up `schema.tableMap[name]`
+ * for the enclave event, then scans each enclave's customs to find
+ * which one owns it:
+ *
+ *   super.submit('messages', {...})  → tableMap.messages='message'
+ *                                    → DM declares 'message'  → DM.message
+ *   super.submit('moments',  {...})  → tableMap.moments='public'
+ *                                    → Personal declares 'public' → Personal.public
+ *
+ * Cross-enclave reads (`schema.reads.<name>.cross_enclave === true`)
+ * route to AppClient.dataview — populated by AppClient.submit.
+ *
+ * Encryption: data_types listed in `schema.encrypt` go through
+ * `this._encrypt(dataType, args)` before submit. Default is pass-
+ * through; subclasses override (e.g. DmSdk wires MLS / dm-crypto).
+ */
+
+import { AppClient, defaultClientPluginRegistry } from './app-client.mjs'
+
+export { defaultClientPluginRegistry } from './app-client.mjs'
+
+/**
+ * Wire the ENC protocol's Ratchet_DM encryption into a ClientPluginRegistry,
+ * replacing the pass-through EnvelopeEncryptFn/DecryptFn defaults from
+ * plugin-client-base. This is how an app (CLI, web-shell,
+ * superapp) opts into REAL DM encryption instead of shipping plaintext —
+ * the gap that previously forced apps to hand-roll their own dm-crypto.
+ *
+ * The crypto is @enc-protocol/plugin-dm-ratchet (Lean-generated Ratchet_DM:
+ * secp256k1 + HKDF-SHA256 chain + XChaCha20-Poly1305, wire-compatible with
+ * zk/cli/node). Per-pair epoch establishment + rotation is application
+ * state, so the host supplies `getEpochSecret(peerPub)` — crypto here,
+ * epoch/session bookkeeping in the app.
+ *
+ * Lazy-imports the plugin so this module loads even where the plugin isn't
+ * installed; only apps that call this pull it in.
+ *
+ * @param {object} plugins  a ClientPluginRegistry
+ * @param {{ getEpochSecret: (peerPub: string) => (Uint8Array|string) }} opts
+ * @returns {Promise<object>} the same registry, with the slots bound
+ */
+export async function registerDmRatchetEncryption(plugins, { getEpochSecret } = {}) {
+  const { makeDmRatchet } = await import('@enc-protocol/plugin-dm-ratchet')
+  const { encrypt, decrypt } = makeDmRatchet({ getEpochSecret })
+  plugins.register('EnvelopeEncryptFn', encrypt)
+  plugins.register('EnvelopeDecryptFn', decrypt)
+  return plugins
+}
+
+/**
+ * Wire ENC's identity-aead (single-owner deterministic AEAD) into a
+ * ClientPluginRegistry. The SPEC-COMPLIANT crypto is the independent plugin
+ * `@enc-protocol/plugin-identity-aead` (Lean-generated IdentityAead:
+ * HKDF-SHA256(identity_priv) keyed by enclave id + XChaCha20-Poly1305 — built
+ * on @enc-protocol/core primitives, NOT part of core). Used by Personal-enclave
+ * `private` (owner-only) content. The owner's long-term `identity_priv` is host
+ * state, supplied via `getIdentityPriv()`; the enclave id is per-call.
+ *
+ * @param {object} plugins  a ClientPluginRegistry
+ * @param {{ getIdentityPriv: () => (Uint8Array|string) }} opts
+ * @returns {Promise<object>} the same registry, with the slots bound
+ */
+export async function registerIdentityAeadEncryption(plugins, { getIdentityPriv } = {}) {
+  const { identityAeadEncrypt, identityAeadDecrypt } = await import('@enc-protocol/plugin-identity-aead')
+  plugins.register('IdentityAeadCryptoFn', (enclaveIdHex, plaintext) =>
+    identityAeadEncrypt(getIdentityPriv(), enclaveIdHex, plaintext))
+  plugins.register('IdentityAeadDecryptFn', (enclaveIdHex, envelope) =>
+    identityAeadDecrypt(getIdentityPriv(), enclaveIdHex, envelope))
+  return plugins
+}
+
+/**
+ * Wire ENC's ecdh-envelope (one-shot sender→recipient confidentiality) into a
+ * ClientPluginRegistry. Crypto = the independent plugin
+ * `@enc-protocol/plugin-ecdh-envelope` (Lean-generated: secp256k1 ECDH +
+ * HKDF-SHA256 + XChaCha20-Poly1305). Used by Personal-enclave `notice` content
+ * (group/DM invites + the handoff carrying a group bootstrap root_secret). The
+ * sender's operational key is host state (`getOpPriv()`); the recipient pub is
+ * per-call.
+ *
+ * @param {object} plugins  a ClientPluginRegistry
+ * @param {{ getOpPriv: () => (Uint8Array|string) }} opts
+ * @returns {Promise<object>} the same registry, with the slots bound
+ */
+export async function registerEcdhEnvelopeEncryption(plugins, { getOpPriv } = {}) {
+  const { ecdhEnvelopeSeal, ecdhEnvelopeOpen } = await import('@enc-protocol/plugin-ecdh-envelope')
+  plugins.register('EcdhEnvelopeCryptoFn', (recipientOpPubHex, payload) =>
+    ecdhEnvelopeSeal(getOpPriv(), recipientOpPubHex, payload))
+  plugins.register('EcdhEnvelopeOpenFn', (envelope) =>
+    ecdhEnvelopeOpen(getOpPriv(), envelope))
+  return plugins
+}
+
+/**
+ * Wire ENC's group Lazy-MLS message encryption into a ClientPluginRegistry.
+ * Crypto = the independent plugin `@enc-protocol/plugin-group-mls-lazy`
+ * (Lean-generated: binary ratchet tree + per-sender HKDF message ratchet +
+ * XChaCha20-Poly1305). Used by Group-enclave message content. Per-epoch group
+ * secrets are app state (epoch establishment + commit distribution), so the
+ * host supplies `getEpochSecret(epochN)`; sender pub/seq are per-call.
+ *
+ * @param {object} plugins  a ClientPluginRegistry
+ * @param {{ getEpochSecret: (epochN: number) => Uint8Array }} opts
+ * @returns {Promise<object>} the same registry, with the slots bound
+ */
+export async function registerGroupMlsLazyEncryption(plugins, { getEpochSecret } = {}) {
+  const { encryptMessage, decryptMessage } = await import('@enc-protocol/plugin-group-mls-lazy')
+  plugins.register('GroupCryptoFn', ({ epochN, senderPubHex, senderSeq, plaintext }) =>
+    encryptMessage({ epochSecret: getEpochSecret(epochN), epochN, senderPubHex, senderSeq, plaintext }))
+  plugins.register('GroupDecryptFn', (envelope) =>
+    decryptMessage({ epochSecret: getEpochSecret(envelope.epoch_n), envelope }))
+  return plugins
+}
+
+/**
+ * Extract the set of write events an enclave declares — from either raw
+ * authored JSON (`manifest.customs[].event`, etc.) or pre-flattened
+ * manifest-loader output (`enclaveConfig.schema[].event`).
+ */
+function eventsFromEnclaveManifest(em) {
+  const out = new Set()
+  // Pre-flattened form (manifest-loader output).
+  const flat = em?.enclaveConfig?.schema
+  if (Array.isArray(flat)) {
+    for (const s of flat) {
+      if (s?.event && s.event !== '*') out.add(s.event)
+    }
+    return out
+  }
+  // Raw authored form: enclaves/<App>.json shape.
+  const m = em?.manifest || em || {}
+  for (const c of (m.customs || [])) {
+    if (c?.event) out.add(c.event)
+  }
+  for (const l of (m.lifecycle || [])) {
+    if (l?.event) out.add(l.event)
+  }
+  for (const mv of (m.moves || [])) {
+    if (mv?.from && mv?.to) out.add(`Move(${mv.from},${mv.to})`)
+  }
+  for (const s of (m.slots || [])) {
+    if (s?.event) out.add(s.key ? `${s.event}(${s.key})` : s.event)
+  }
+  return out
+}
+
+export class AppSdk {
+  constructor(opts = {}) {
+    this.opts = opts
+    this.client = new AppClient(opts)
+    this.app = this.client.app
+    this.schema = this.client.schema
+    this.appId = this.client.appId
+
+    /** event name → enclave name */
+    this._eventToEnclave = new Map()
+    for (const [enclaveName, e] of this.client.enclaves) {
+      for (const event of eventsFromEnclaveManifest(e.manifest)) {
+        if (!this._eventToEnclave.has(event)) {
+          this._eventToEnclave.set(event, enclaveName)
+        }
+      }
+    }
+  }
+
+  async init() {
+    await this.client.init()
+    return this
+  }
+
+  _resolveEnclave(event) {
+    const enclave = this._eventToEnclave.get(event)
+    if (!enclave) {
+      throw new Error(`AppSdk: no enclave declares event "${event}" (app: ${this.appId})`)
+    }
+    return enclave
+  }
+
+  /**
+   * Resolve `name` (may be an app data_type/read OR an enclave event
+   * directly) to (enclave, event). Delegates to the EventResolverFn
+   * plugin from the ClientPluginRegistry. Default impl preserves the
+   * legacy tableMap-then-event-fallthrough behavior.
+   * @returns {{ enclave: string, event: string }}
+   */
+  _resolve(name) {
+    // Build the enclaveEvents Map the plugin expects: enclave → Set<event>.
+    if (!this._enclaveEvents) {
+      this._enclaveEvents = new Map()
+      for (const [enclaveName, e] of this.client.enclaves) {
+        const events = eventsFromEnclaveManifest(e.manifest)
+        this._enclaveEvents.set(enclaveName, events)
+      }
+    }
+    const resolver = this.client.plugins.get('EventResolverFn')
+    if (resolver) {
+      return resolver({
+        name,
+        schema: this.schema,
+        enclaveEvents: this._enclaveEvents,
+        appId: this.appId,
+      })
+    }
+    // Fallback path — registry has no resolver bound. Preserves legacy.
+    const mapped = this.schema.tableMap?.[name]
+    if (mapped) {
+      return { enclave: this._resolveEnclave(mapped), event: mapped }
+    }
+    if (this._eventToEnclave.has(name)) {
+      return { enclave: this._eventToEnclave.get(name), event: name }
+    }
+    throw new Error(
+      `AppSdk: "${name}" is neither a data_type/read nor an enclave event ` +
+      `in app ${this.appId}`,
+    )
+  }
+
+  /**
+   * Submit a write. `name` may be an app data_type (resolved via
+   * tableMap) or an enclave event directly.
+   */
+  async submit(name, args = {}) {
+    const { enclave, event } = this._resolve(name)
+    return this.client.submit(enclave, event, args)
+  }
+
+  /**
+   * Query a read view OR enclave event directly.
+   *
+   * Resolution:
+   *   1. cross_enclave read → AppClient.dataview.query(name)
+   *   2. tableMap → enclave event → enclave.query
+   *   3. enclave event directly
+   */
+  async query(name) {
+    const read = this.schema.reads?.[name]
+    if (read?.cross_enclave) {
+      const rows = this.client.dataview?.query(name)
+      if (rows == null) {
+        throw new Error(
+          `AppSdk: cross_enclave read "${name}" — no dataview source configured ` +
+          `(check infra.cross_enclave_reads)`,
+        )
+      }
+      return rows
+    }
+    const { enclave, event } = this._resolve(name)
+    return this.client.query(enclave, event)
+  }
+
+  /**
+   * Envelope-encrypt hook. Default impl: pass-through via
+   * EnvelopeEncryptFn plugin (which is also pass-through by default).
+   * Per-app SDK subclasses can still override directly for backward
+   * compat; subclasses are checked first.
+   */
+  async _encrypt(dataType, args, opts) {
+    const encryptFn = this.client.plugins.get('EnvelopeEncryptFn')
+    if (encryptFn) return encryptFn(dataType, args, opts)
+    return args
+  }
+
+  /**
+   * Envelope-decrypt hook. Pairs with _encrypt — same plugin slot.
+   * Default impl is pass-through. The Subscriber uses this when an
+   * event arrives flagged as encrypted.
+   */
+  async _decrypt(eventType, content, fromPub) {
+    const decryptFn = this.client.plugins.get('EnvelopeDecryptFn')
+    if (decryptFn) return decryptFn(eventType, content, fromPub)
+    return content
+  }
+
+  /** Pass-through to AppClient for primitive operations. */
+  raw() { return this.client }
+
+  whoami() {
+    return {
+      ...this.client.whoami(),
+      schemaName: this.schema.name || null,
+      dataTypes: Object.keys(this.schema.data_types || {}),
+      reads: Object.keys(this.schema.reads || {}),
+    }
+  }
+}

package/dataview.mjs

@@ -0,0 +1,113 @@
+/**
+ * DataView — minimal in-memory dataview for AppClient's cross_enclave reads.
+ *
+ * Reads `apps/<id>/infra.json`'s `manifest.cross_enclave_reads` to learn
+ * how each cross-enclave view is sourced:
+ *
+ *   "profiles": {
+ *     "from": "Personal.Shared(profile)",   // source enclave + event
+ *     "via":  "dataview",                   // protocol (we handle 'dataview')
+ *     "key":  "id_pub",                     // optional UPSERT key
+ *     "access": "read"
+ *   }
+ *
+ * AppClient hooks into `submit` so events that match any view's source
+ * are captured into `this.rows[view]`. AppSdk.query routes
+ * cross_enclave reads here.
+ *
+ * The actual ingest behavior is delegated to the `IngestStrategyFn`
+ * plugin (`@enc-protocol/plugin-client-base/ingest` by default).
+ * The default reference impl is identical to the previous inline
+ * behavior — append-only for regular event sources, UPSERT for
+ * `Shared(...)` slots, registry snapshots, or explicit `key` views.
+ *
+ * Production dataview (the real DO) also handles encrypted Push wire
+ * envelopes; that's the `WireDecryptFn` plugin on the server side.
+ */
+
+import {
+  ingest as defaultIngest,
+  initStorageForView as defaultInitStorage,
+} from '@enc-protocol/plugin-client-base/ingest'
+
+export class DataView {
+  /**
+   * @param {object} crossReads  apps/<id>/infra.json's
+   *   manifest.cross_enclave_reads — view name → { from, via, key, access }
+   */
+  /**
+   * @param {object} crossReads  apps/<id>/infra.json's
+   *   manifest.cross_enclave_reads — view name → { from, via, key, access }
+   * @param {object} [opts]
+   * @param {function} [opts.ingestFn]    IngestStrategyFn override (default: plugin-client-base/ingest)
+   * @param {function} [opts.initStorageFn]  storage-init override (default: same plugin)
+   */
+  constructor(crossReads = {}, opts = {}) {
+    /** @type {Map<string, {sourceEnclave: string, sourceEvent: string, isSlot: boolean, slotName: string|null, key: string|null}>} */
+    this.views = new Map()
+    /** @type {Map<string, Map<string, object>|object[]>} */
+    this.rows = new Map()
+    this._ingestFn = opts.ingestFn || defaultIngest
+    this._initStorageFn = opts.initStorageFn || defaultInitStorage
+
+    for (const [viewName, cfg] of Object.entries(crossReads)) {
+      if (cfg.via !== 'dataview') continue   // 'enclave' routing isn't us
+      const from = String(cfg.from || '')
+      // Parse "Personal.Shared(profile)" or "Group.notice"
+      const m = from.match(/^([^.]+)\.(.+)$/)
+      if (!m) continue
+      const sourceEnclave = m[1]
+      const eventExpr = m[2]
+      const slotMatch = eventExpr.match(/^Shared\(([^)]+)\)$/)
+      const view = {
+        sourceEnclave,
+        sourceEvent: eventExpr,
+        isSlot: !!slotMatch,
+        slotName: slotMatch ? slotMatch[1] : null,
+        key: cfg.key || null,
+      }
+      this.views.set(viewName, view)
+      this.rows.set(viewName, this._initStorageFn(view))
+    }
+  }
+
+  /** Source enclaves an AppClient needs to watch — caller hooks submit on these. */
+  watchedEnclaves() {
+    const out = new Set()
+    for (const v of this.views.values()) out.add(v.sourceEnclave)
+    return out
+  }
+
+  /**
+   * Called by AppClient when an event is submitted on a watched enclave.
+   * Delegates to the configured IngestStrategyFn plugin.
+   *
+   * @param {string} enclaveName  enclave the event came from
+   * @param {object} ev           parsed event { type, content, from, timestamp, id, parsed? }
+   */
+  ingest(enclaveName, ev) {
+    this._ingestFn({ enclaveName, event: ev, views: this.views, rows: this.rows })
+  }
+
+  /** Query a view; returns rows array (reverse-chronological for append-only). */
+  query(viewName) {
+    const storage = this.rows.get(viewName)
+    if (!storage) return null   // view not configured
+    if (storage instanceof Map) return [...storage.values()]
+    return [...storage].reverse()
+  }
+
+  /** True if this view is known. */
+  has(viewName) { return this.views.has(viewName) }
+}
+
+/**
+ * Build a DataView from an in-memory infra manifest.
+ * Caller (Node loader, vite bundler, etc.) supplies the parsed JSON.
+ */
+export function dataViewFromInfra(infraManifest, opts) {
+  const crossReads = infraManifest?.manifest?.cross_enclave_reads
+    || infraManifest?.cross_enclave_reads
+    || {}
+  return new DataView(crossReads, opts)
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@enc-protocol/app-sdk-base",
+  "version": "0.9.0",
+  "type": "module",
+  "description": "Platform-agnostic base SDK for per-app ENC protocol clients. AppSdk + AppClient + DataView. Manifests + adapter injected by caller.",
+  "main": "./app-sdk.mjs",
+  "files": [
+    "app-sdk.mjs",
+    "app-client.mjs",
+    "dataview.mjs",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./app-sdk.mjs",
+    "./app-sdk": "./app-sdk.mjs",
+    "./app-client": "./app-client.mjs",
+    "./dataview": "./dataview.mjs"
+  },
+  "keywords": [
+    "enc-protocol",
+    "sdk",
+    "multi-enclave",
+    "platform-agnostic",
+    "core",
+    "public"
+  ],
+  "dependencies": {
+    "@enc-protocol/plugin-runtime": "^0.9.0",
+    "@enc-protocol/plugin-client-base": "^0.9.0"
+  },
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  }
+}