@kehto/runtime 0.25.2 → 0.26.1

package/README.md

@@ -40,6 +40,68 @@ The runtime is built around the current draft dispatch contract from `@napplet/c
 
 Signing is shell-mediated inside `relay.publish` / `relay.publishEncrypted` (NIP-44 default, NIP-04 opt-in). The legacy signer domain is dissolved — napplets never see a host-injected nostr object and cannot call signer-sign RPCs directly.
 
+### Storage quota administration
+
+Hosts can call `runtime.aclState.setStateQuota(pubkey, dTag, aggregateHash, bytes)`
+to update the exact principal's live storage limit. `bytes` must be an integer
+from zero through `Number.MAX_SAFE_INTEGER`; malformed input throws `RangeError`
+before changing policy. Call `aclState.persist()` separately to save the quota.
+The default remains 524,288 bytes. Grants and block status are preserved.
+
+The existing storage handler consumes this same quota across shared and instance
+storage for that principal, counting UTF-8 bytes including scoped storage keys.
+Lowering a quota preserves stored values; writes that exceed the new limit fail
+until data is removed or the host increases the quota. Zero prevents nonempty
+storage writes while reads/removals remain subject to their existing ACL checks.
+
+This host administration API conforms to [NAP-STORAGE draft PR #3 at
+`4f4cf0ca7ecbd24c284a5d63bcd85e3de6af37ca`](https://github.com/napplet/naps/blob/4f4cf0ca7ecbd24c284a5d63bcd85e3de6af37ca/naps/NAP-STORAGE.md).
+It adds no napplet-callable quota setter or wire field.
+
+### ACL principal enumeration
+
+`aclState.getAllEntries()` and `getEntry()` return `dTag` and `aggregateHash`
+alongside the policy fields. Use these values with keyed ACL methods; two
+principals with identical grants still have distinct identities after reload.
+Enumeration keeps `pubkey: ''` because ACL identity is keyed by dTag and artifact
+hash. Returned objects and capability arrays are detached from the owned state.
+
+```ts
+for (const entry of runtime.aclState.getAllEntries()) {
+  runtime.aclState.revoke(entry.pubkey, entry.dTag, entry.aggregateHash, 'relay:read');
+}
+```
+
+This host API adds no protocol messages and does not change serialized ACL keys.
+Custom `AclEntryExternal` producers must populate the two required identity fields.
+
+### ACL persistence outcomes
+
+ACL mutations update live policy immediately. Revoke/block observers run
+synchronously after that change, before any explicit save. `aclState.persist()`
+returns `true` when the persistence backend completes and `false` if it throws.
+A failed save never rolls back live policy or reactivates retired subscriptions;
+a newly loaded container can still see the last successfully saved policy.
+
+`aclState.clear()` resets live policy to its configured default and attempts to
+clear storage, returning the same success boolean. A failed clear leaves that
+live reset in place and old durable data unchanged. Retry persistence or clearing
+after handling the backend failure. These results report the synchronous backend
+contract, not physical disk durability. Hosts must not swallow backend errors if
+they want the container to detect failure.
+
+```ts
+runtime.aclState.revoke('', dTag, aggregateHash, 'relay:read');
+if (!runtime.aclState.persist()) {
+  showSaveError('Access is revoked for this session, but the policy was not saved.');
+}
+```
+
+Runtime destruction remains best-effort; hosts requiring an actionable save
+result should call `persist()` before teardown. This host API policy is outside
+the NAP wire contract. No old-use warning can detect callers ignoring a return
+value; see [the compatibility register](https://github.com/kehto/web/blob/main/docs/compatibility.md).
+
 ### NAP-RELAY subscription revocation
 
 Revoking `relay:read` or blocking a principal immediately retires ordinary relay

package/dist/index.d.ts

@@ -530,6 +530,10 @@ type PendingUpdateNotifier = (windowId: string) => void;
 /** External ACL entry — used in shell commands (shell:acl-get etc.). */
 interface AclEntryExternal {
     pubkey: string;
+    /** Verified napplet identifier. */
+    dTag: string;
+    /** Verified artifact hash. */
+    aggregateHash: string;
     capabilities: Capability[];
     blocked: boolean;
     stateQuota?: number;
@@ -633,6 +637,8 @@ interface ServiceHandler {
      * @param windowId - The destroyed napplet's window identifier
      */
     onWindowDestroyed?(windowId: string): void;
+    /** Revoke live output when this endpoint loses a capability or is blocked. */
+    onCapabilityRevoked?(windowId: string, capability: Capability | null): void;
 }
 /**
  * Registry of services available to napplets.
@@ -1037,7 +1043,7 @@ type AclMutation = {
     readonly dTag: string;
     readonly aggregateHash: string;
 };
-/** Receives synchronous ACL authority changes after persistence succeeds. */
+/** Receives synchronous in-memory revoke/block changes, before any explicit persistence. */
 type AclMutationObserver = (mutation: AclMutation) => void;
 /**
  * ACL state container — wraps @kehto/acl's pure functions with
@@ -1060,9 +1066,40 @@ interface AclStateContainer {
     getEntry(pubkey: string, dTag: string, aggregateHash: string): AclEntryExternal | undefined;
     getAllEntries(): AclEntryExternal[];
     getStateQuota(pubkey: string, dTag: string, aggregateHash: string): number;
-    persist(): void;
+    /**
+     * Set a principal's live storage quota without changing grants or stored data.
+     * Call persist() separately to save the policy.
+     * @param pubkey - Retained identity argument; policy is keyed by dTag and hash.
+     * @param dTag - Verified napplet identifier.
+     * @param aggregateHash - Verified artifact hash.
+     * @param bytes - Integer byte count from zero through Number.MAX_SAFE_INTEGER.
+     * @throws RangeError if bytes is not a non-negative safe integer.
+     * @example
+     * ```ts
+     * acl.setStateQuota('', dTag, aggregateHash, 1024 * 1024);
+     * acl.persist();
+     * ```
+     */
+    setStateQuota(pubkey: string, dTag: string, aggregateHash: string, bytes: number): void;
+    /**
+     * Save live state without rolling back live policy on failure.
+     * @returns True if the backend completed; false if it threw.
+     * @example
+     * ```ts
+     * if (!acl.persist()) showSaveError();
+     * ```
+     */
+    persist(): boolean;
     load(): void;
-    clear(): void;
+    /**
+     * Reset live state to the configured default and attempt to clear storage.
+     * @returns True if storage cleared; false if only the live reset succeeded.
+     * @example
+     * ```ts
+     * if (!acl.clear()) showSaveError();
+     * ```
+     */
+    clear(): boolean;
 }
 /**
  * Create an ACL state container backed by @kehto/acl and persisted

package/dist/index.js

@@ -122,6 +122,7 @@ import {
   serialize,
   deserialize,
   getQuota,
+  setQuota,
   CAP_RELAY_READ,
   CAP_RELAY_WRITE,
   CAP_CACHE_READ,
@@ -237,15 +238,20 @@ function createAclState(persistence, defaultPolicy = "permissive", onMutation) {
       if (!entry) return void 0;
       return {
         pubkey: pubkey || "",
+        dTag,
+        aggregateHash,
         capabilities: bitsToCapabilities(entry.caps),
         blocked: entry.blocked,
         stateQuota: entry.quota
       };
     },
     getAllEntries() {
-      return Object.entries(state.entries).map(([, entry]) => {
+      return Object.entries(state.entries).map(([key, entry]) => {
+        const separator = key.lastIndexOf(":");
         return {
           pubkey: "",
+          dTag: key.slice(0, separator),
+          aggregateHash: key.slice(separator + 1),
           capabilities: bitsToCapabilities(entry.caps),
           blocked: entry.blocked,
           stateQuota: entry.quota
@@ -256,10 +262,20 @@ function createAclState(persistence, defaultPolicy = "permissive", onMutation) {
       const id = toIdentity(pubkey, dTag, aggregateHash);
       return getQuota(state, id);
     },
+    setStateQuota(pubkey, dTag, aggregateHash, bytes) {
+      if (!Number.isSafeInteger(bytes) || bytes < 0) {
+        throw new RangeError("State quota must be a non-negative safe integer byte count");
+      }
+      const id = toIdentity(pubkey, dTag, aggregateHash);
+      ensureRuntimeDefaultEntry(id);
+      state = setQuota(state, id, bytes);
+    },
     persist() {
       try {
         persistence.persist(serialize(state));
+        return true;
       } catch {
+        return false;
       }
     },
     load() {
@@ -275,7 +291,9 @@ function createAclState(persistence, defaultPolicy = "permissive", onMutation) {
       state = createState(defaultPolicy);
       try {
         persistence.persist("");
+        return true;
       } catch {
+        return false;
       }
     }
   };
@@ -1737,8 +1755,8 @@ function handleMediaMessage(context, windowId, msg) {
     hooks.sendToNapplet(windowId, {
       type: "media.session.create.result",
       id: m.id ?? "",
-      sessionId: m.sessionId ?? "",
-      owner: m.owner
+      owner: m.owner,
+      error: "media service unavailable"
     });
   }
 }
@@ -2175,11 +2193,15 @@ function createRuntime(hooks) {
   });
   let incRuntime = null;
   const aclState = createAclState(hooks.aclPersistence, "permissive", (mutation) => {
-    if (mutation.type === "revoke" && mutation.capability !== "relay:read") return;
     for (const entry of sessionRegistry.getAllEntries()) {
       if (entry.dTag === mutation.dTag && entry.aggregateHash === mutation.aggregateHash) {
-        revokeRelaySubscriptions({ hooks, serviceRegistry, subscriptions }, entry.windowId);
-        incRuntime?.revokeWindow(entry.windowId);
+        for (const service of Object.values(serviceRegistry)) {
+          service.onCapabilityRevoked?.(entry.windowId, mutation.type === "block" ? null : mutation.capability);
+        }
+        if (mutation.type === "block" || mutation.capability === "relay:read") {
+          revokeRelaySubscriptions({ hooks, serviceRegistry, subscriptions }, entry.windowId);
+          incRuntime?.revokeWindow(entry.windowId);
+        }
       }
     }
   });