@kehto/runtime 0.25.1 → 0.26.0

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
@@ -205,6 +267,11 @@ runtime.handleMessage('window-1', {
 - `createSessionRegistry` — bidirectional windowId ↔ `SessionEntry` store
 - `createNappKeyRegistry` — deprecated alias retained for v1.1 migration consumers
 
+`unregister(windowId)` retires the window's registration, lookup state, and pending
+update, including NIP-5D sessions whose pubkey is empty. Repeated calls are safe.
+If a newer window owns the same pubkey lookup, that newer entry is preserved;
+use `getEntryByWindowId` to distinguish live windows sharing an empty pubkey.
+
 `runtime.sessionRegistry.register(windowId, entry)` establishes a fresh trusted
 source lifecycle and retires that window's previous initialization burst budget,
 including when the host reuses the window ID, timestamp, or entry object. Ordinary

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;
@@ -959,7 +963,7 @@ declare function formatDenialReason(capability: Capability): string;
 interface SessionRegistry {
     /** Establish a fresh host-attested lifecycle, mapping windowId to pubkey and vice versa. */
     register(windowId: string, entry: SessionEntry): void;
-    /** Unregister a napplet by windowId, removing both mappings. */
+    /** Remove a window and its owned mappings, including empty-pubkey sessions. */
     unregister(windowId: string): void;
     /** Get the pubkey associated with a windowId. */
     getPubkey(windowId: string): string | undefined;
@@ -1037,7 +1041,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 +1064,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

@@ -51,10 +51,10 @@ function createSessionRegistry(notifier, onRegister) {
     },
     unregister(windowId) {
       const pubkey = byWindowId.get(windowId);
-      if (pubkey) {
+      if (pubkey !== void 0 && byPubkey.get(pubkey)?.windowId === windowId) {
         byPubkey.delete(pubkey);
-        byWindowId.delete(windowId);
       }
+      byWindowId.delete(windowId);
       byWindowIdEntry.delete(windowId);
       pendingUpdates.delete(windowId);
     },
@@ -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;
       }
     }
   };