@enbox/agent 0.6.5 → 0.6.6

package/src/identity-api.ts

@@ -54,7 +54,7 @@ export class AgentIdentityApi<TKeyManager extends AgentKeyManager = AgentKeyMana
    */
   private _agent?: EnboxPlatformAgent<TKeyManager>;
 
-  private _store: AgentDataStore<IdentityMetadata>;
+  private readonly _store: AgentDataStore<IdentityMetadata>;
 
   constructor({ agent, store }: IdentityApiParams<TKeyManager> = {}) {
     this._agent = agent;
@@ -256,11 +256,12 @@ export class AgentIdentityApi<TKeyManager extends AgentKeyManager = AgentKeyMana
       };
 
       // if no other services exist, create a new array with the DWN service
-      if (!portableDid.document.service) {
-        portableDid.document.service = [newDwnService];
-      } else {
-        // otherwise, push the new DWN service to the existing services
+      if (portableDid.document.service) {
+        // push the new DWN service to the existing services
         portableDid.document.service.push(newDwnService);
+      } else {
+        // no other services exist, create a new array with the DWN service
+        portableDid.document.service = [newDwnService];
       }
     }
 

package/src/index.ts

@@ -32,6 +32,7 @@ export * from './identity-api.js';
 export * from './local-dwn.js';
 export * from './local-key-manager.js';
 export * from './permissions-api.js';
+export * from './secret-store.js';
 export * from './store-data.js';
 export * from './store-did.js';
 export * from './store-identity.js';

package/src/local-dwn.ts

@@ -62,9 +62,9 @@ export class LocalDwnDiscovery {
   private _cacheExpiry = 0;
 
   constructor(
-    private _rpcClient: EnboxRpc,
-    private _cacheTtlMs = 10_000,
-    private _discoveryFile?: DwnDiscoveryFile,
+    private readonly _rpcClient: EnboxRpc,
+    private readonly _cacheTtlMs = 10_000,
+    private readonly _discoveryFile?: DwnDiscoveryFile,
   ) {}
 
   /**

package/src/local-key-manager.ts

@@ -177,7 +177,7 @@ export class LocalKeyManager implements AgentKeyManager {
    * that implements a specific cryptographic algorithm. This map is used to cache and reuse
    * instances for performance optimization, ensuring that each algorithm is instantiated only once.
    */
-  private _algorithmInstances: Map<AlgorithmConstructor, InstanceType<typeof CryptoAlgorithm>> = new Map();
+  private readonly _algorithmInstances: Map<AlgorithmConstructor, InstanceType<typeof CryptoAlgorithm>> = new Map();
 
   /**
    * The `_keyStore` private variable in `LocalKeyManager` is a {@link AgentDataStore} instance used
@@ -187,7 +187,7 @@ export class LocalKeyManager implements AgentKeyManager {
    * persistent storage, providing flexibility in key management according to the application's
    * requirements.
    */
-  private _keyStore: AgentDataStore<Jwk>;
+  private readonly _keyStore: AgentDataStore<Jwk>;
 
   constructor({ agent, keyStore }: LocalKmsParams = {}) {
     this._agent = agent;

package/src/permissions-api.ts

@@ -1,6 +1,6 @@
 import type { EnboxAgent } from './types/agent.js';
 import type { CreateGrantParams, CreateRequestParams, CreateRevocationParams, FetchPermissionRequestParams, FetchPermissionsParams, GetPermissionParams, IsGrantRevokedParams, PermissionGrantEntry, PermissionRequestEntry, PermissionRevocationEntry, PermissionsApi } from './types/permissions.js';
-import type { DwnDataEncodedRecordsWriteMessage, DwnMessageParams, DwnMessagesPermissionScope, DwnPermissionScope, DwnProtocolPermissionScope, DwnRecordsPermissionScope, ProcessDwnRequest } from './types/dwn.js';
+import type { DwnDataEncodedRecordsWriteMessage, DwnMessageParams, DwnPermissionScope, DwnRecordsPermissionScope, ProcessDwnRequest } from './types/dwn.js';
 import type { PermissionGrant, PermissionGrantData, PermissionRequestData, PermissionRevocationData } from '@enbox/dwn-sdk-js';
 
 import { isRecordsType } from './dwn-api.js';
@@ -11,7 +11,7 @@ import { DwnInterface, DwnPermissionGrant, DwnPermissionRequest } from './types/
 export class AgentPermissionsApi implements PermissionsApi {
 
   /** cache for fetching a permission {@link PermissionGrant}, keyed by a specific MessageType and protocol */
-  private _cachedPermissions: TtlCache<string, PermissionGrantEntry> = new TtlCache({ ttl: 60 * 1000 });
+  private readonly _cachedPermissions: TtlCache<string, PermissionGrantEntry> = new TtlCache({ ttl: 60 * 1000 });
 
   private _agent?: EnboxAgent;
 
@@ -445,11 +445,15 @@ export class AgentPermissionsApi implements PermissionsApi {
     const scope = grant.scope;
     const scopeMessageType = scope.interface + scope.method;
 
-    // Messages.Read is a unified scope that covers Messages.Read, Messages.Sync, and Messages.Subscribe.
-    // When looking for a MessagesSync or MessagesSubscribe grant, also accept a MessagesRead grant.
-    const isMessagesScopeMatch = scopeMessageType === messageType
-      || (scopeMessageType === DwnInterface.MessagesRead
-        && (messageType === DwnInterface.MessagesSync || messageType === DwnInterface.MessagesSubscribe));
+    // Messages.Read is the only valid Messages scope and covers Read, Sync, and Subscribe operations.
+    // Defensively require method === Read so malformed/legacy grants with method Sync/Subscribe
+    // are rejected rather than treated as valid scopes.
+    const isMessagesScopeMatch = scope.interface === 'Messages'
+      ? scope.method === 'Read'
+        && (messageType === DwnInterface.MessagesRead
+          || messageType === DwnInterface.MessagesSync
+          || messageType === DwnInterface.MessagesSubscribe)
+      : scopeMessageType === messageType;
 
     if (isMessagesScopeMatch) {
       if (isRecordsType(messageType)) {
@@ -474,7 +478,7 @@ export class AgentPermissionsApi implements PermissionsApi {
           return true;
         }
       } else {
-        const messagesScope = scope as DwnMessagesPermissionScope | DwnProtocolPermissionScope;
+        const messagesScope = scope;
         // Checks for unrestricted protocol scope, if no protocol is defined in the scope it is unrestricted
         if (messagesScope.protocol === undefined) {
           return true;

package/src/prototyping/crypto/jose/jwe-flattened.ts

@@ -301,24 +301,24 @@ export class FlattenedJwe {
     const tag = decodeHeaderParam('tag', jwe.tag);
 
     // Decode the JWE Ciphertext to a byte array, and if present, append the Authentication Tag.
-    const ciphertext = tag !== undefined
-      ? new Uint8Array([
+    const ciphertext = tag === undefined
+      ? Convert.base64Url(jwe.ciphertext).toUint8Array()
+      : new Uint8Array([
         ...Convert.base64Url(jwe.ciphertext).toUint8Array(),
         ...(tag ?? [])
-      ])
-      : Convert.base64Url(jwe.ciphertext).toUint8Array();
+      ]);
 
     // If the JWE Additional Authenticated Data (AAD) is present, the Additional Authenticated Data
     // input to the Content Encryption Algorithm is
     // ASCII(Encoded Protected Header || '.' || BASE64URL(JWE AAD)). If the JWE AAD is absent, the
     // Additional Authenticated Data is ASCII(BASE64URL(UTF8(JWE Protected Header))).
-    const additionalData = jwe.aad !== undefined
-      ? new Uint8Array([
+    const additionalData = jwe.aad === undefined
+      ? Convert.string(jwe.protected ?? '').toUint8Array()
+      : new Uint8Array([
         ...Convert.string(jwe.protected ?? '').toUint8Array(),
         ...Convert.string('.').toUint8Array(),
         ...Convert.string(jwe.aad).toUint8Array()
-      ])
-      : Convert.string(jwe.protected ?? '').toUint8Array();
+      ]);
 
     // Decrypt the JWE using the Content Encryption Key (CEK) with:
     // - Key Manager: If the CEK is a Key Identifier.

package/src/secret-store.ts

@@ -0,0 +1,173 @@
+import type { KeyValueStore } from '@enbox/common';
+
+import type { IdentityVault } from './types/identity-vault.js';
+
+/**
+ * Options for storing a secret.
+ */
+export type SecretStorePutOptions = {
+  /**
+   * ISO-8601 timestamp after which the secret is considered expired.
+   *
+   * Expired secrets are silently deleted on the next {@link SecretStore.get}
+   * call and `undefined` is returned.
+   */
+  expiresAt?: string;
+};
+
+/**
+ * Platform-agnostic interface for storing classified secrets encrypted at rest
+ * by the agent vault.
+ *
+ * Implementations must ensure that plaintext secret material is never persisted
+ * to browser-accessible storage such as `localStorage` or `sessionStorage`.
+ */
+export interface SecretStore {
+  /**
+   * Store a secret, encrypted at rest with the vault key.
+   *
+   * @param key - Unique identifier for the secret.
+   * @param value - The secret bytes to store.
+   * @param options - Optional metadata (e.g. TTL).
+   * @throws If the vault is locked.
+   */
+  put(key: string, value: Uint8Array, options?: SecretStorePutOptions): Promise<void>;
+
+  /**
+   * Retrieve and decrypt a secret.
+   *
+   * Returns `undefined` if the key does not exist or the secret has expired.
+   *
+   * @param key - The identifier used when the secret was stored.
+   * @throws If the vault is locked.
+   */
+  get(key: string): Promise<Uint8Array | undefined>;
+
+  /**
+   * Delete a secret.
+   *
+   * @param key - The identifier used when the secret was stored.
+   * @returns `true` if the key existed and was removed, `false` otherwise.
+   */
+  delete(key: string): Promise<boolean>;
+}
+
+// ---------------------------------------------------------------------------
+//  Internal envelope persisted in the backing KeyValueStore.
+// ---------------------------------------------------------------------------
+
+/** @internal */
+type SecretEnvelope = {
+  /** Compact JWE encrypted by the vault's content encryption key. */
+  jwe: string;
+
+  /** Optional ISO-8601 expiry timestamp. */
+  expiresAt?: string;
+};
+
+// ---------------------------------------------------------------------------
+//  VaultBackedSecretStore
+// ---------------------------------------------------------------------------
+
+/**
+ * Vault-backed implementation of {@link SecretStore}.
+ *
+ * Secrets are encrypted with the vault's content encryption key (AES-256-GCM
+ * via `dir` algorithm) before being persisted to the backing
+ * {@link KeyValueStore}. The vault must be unlocked for {@link put} and
+ * {@link get} operations; {@link delete} does not require the vault to be
+ * unlocked since it only removes the encrypted envelope.
+ */
+export class VaultBackedSecretStore implements SecretStore {
+  private readonly _vault: IdentityVault;
+  private readonly _store: KeyValueStore<string, string>;
+
+  constructor({ vault, store }: {
+    vault : IdentityVault;
+    store : KeyValueStore<string, string>;
+  }) {
+    this._vault = vault;
+    this._store = store;
+  }
+
+  public async put(
+    key: string,
+    value: Uint8Array,
+    options?: SecretStorePutOptions,
+  ): Promise<void> {
+    // vault.encryptData() throws if the vault is locked.
+    const jwe = await this._vault.encryptData({ plaintext: value });
+
+    const envelope: SecretEnvelope = { jwe };
+    if (options?.expiresAt !== undefined) {
+      envelope.expiresAt = options.expiresAt;
+    }
+
+    await this._store.set(key, JSON.stringify(envelope));
+  }
+
+  public async get(key: string): Promise<Uint8Array | undefined> {
+    const raw = await this._store.get(key);
+    if (raw === undefined) { return undefined; }
+
+    const envelope = JSON.parse(raw) as SecretEnvelope;
+
+    // Purge expired secrets.
+    if (envelope.expiresAt !== undefined && new Date(envelope.expiresAt).getTime() <= Date.now()) {
+      await this._store.delete(key);
+      return undefined;
+    }
+
+    // vault.decryptData() throws if the vault is locked.
+    return this._vault.decryptData({ jwe: envelope.jwe });
+  }
+
+  public async delete(key: string): Promise<boolean> {
+    const existing = await this._store.get(key);
+    if (existing === undefined) { return false; }
+    await this._store.delete(key);
+    return true;
+  }
+}
+
+// ---------------------------------------------------------------------------
+//  InMemorySecretStore
+// ---------------------------------------------------------------------------
+
+/**
+ * In-memory implementation of {@link SecretStore} for testing.
+ *
+ * Secrets are stored as plain `Uint8Array` values in a `Map` — no encryption,
+ * no persistence. This is suitable only for unit tests.
+ */
+export class InMemorySecretStore implements SecretStore {
+  private readonly _store = new Map<string, { value: Uint8Array; expiresAt?: string }>();
+
+  public async put(
+    key: string,
+    value: Uint8Array,
+    options?: SecretStorePutOptions,
+  ): Promise<void> {
+    this._store.set(key, {
+      value     : new Uint8Array(value),
+      expiresAt : options?.expiresAt,
+    });
+  }
+
+  public async get(key: string): Promise<Uint8Array | undefined> {
+    const entry = this._store.get(key);
+    if (entry === undefined) { return undefined; }
+
+    // Purge expired secrets.
+    if (entry.expiresAt !== undefined && new Date(entry.expiresAt).getTime() <= Date.now()) {
+      this._store.delete(key);
+      return undefined;
+    }
+
+    return new Uint8Array(entry.value);
+  }
+
+  public async delete(key: string): Promise<boolean> {
+    return this._store.delete(key);
+  }
+}

package/src/store-data.ts

@@ -69,9 +69,14 @@ export class DwnDataStore<TStoreObject extends Record<string, any> = Jwk> implem
    * Cache of tenant DIDs that have been initialized with the protocol.
    * This is used to avoid redundant protocol initialization requests.
    *
-   * Since these are default protocols and unlikely to change, we can use a long TTL.
+   * Uses TtlCache with a 1-hour TTL rather than a permanent Set so that
+   * protocol state changes by another agent/process (protocol upgrade,
+   * reinstall, or tenant clear) are eventually re-detected. Both this
+   * and `_tenantEncryptionActive` must share the same TTL so they expire
+   * together — otherwise `initialize()` could return early while the
+   * encryption state is stale.
    */
-  protected _protocolInitializedCache: TtlCache<string, boolean> = new TtlCache({ ttl: ms('21 days'), max: 1000 });
+  protected _protocolInitializedCache: TtlCache<string, boolean> = new TtlCache({ ttl: ms('1 hour'), max: 1000 });
 
   /**
    * The protocol assigned to this storage instance.
@@ -84,8 +89,15 @@ export class DwnDataStore<TStoreObject extends Record<string, any> = Jwk> implem
    * When any type in `_recordProtocolDefinition` has `encryptionRequired: true`,
    * this will always be `true` after successful initialization (since
    * installation fails if encryption is not possible).
+   *
+   * Uses the same 1-hour TTL as `_protocolInitializedCache` so both
+   * caches expire and re-derive together. See comment above.
    */
-  private _tenantEncryptionActive: TtlCache<string, boolean> = new TtlCache({ ttl: ms('21 days'), max: 1000 });
+  private readonly _tenantEncryptionActive: TtlCache<string, boolean> = new TtlCache({ ttl: ms('1 hour'), max: 1000 });
+
+  /** Cached result of the `encryptionRequired` check on the protocol definition.
+   *  Computed lazily on first access — the definition is immutable after assignment. */
+  private _encryptionRequired: boolean | undefined;
 
   /**
    * Properties to use when writing and querying records with the DWN store.
@@ -218,7 +230,11 @@ export class DwnDataStore<TStoreObject extends Record<string, any> = Jwk> implem
    */
   public async initialize({ tenant, agent }: DataStoreTenantParams): Promise<void> {
     const tenantDid = await getDataStoreTenant({ agent, tenant });
-    if (this._protocolInitializedCache.has(tenantDid)) {
+    // Short-circuit only when both caches are present. If the encryption
+    // cache has expired or was cleared while the init cache survived,
+    // re-derive instead of silently dropping encryption.
+    if (this._protocolInitializedCache.has(tenantDid)
+        && (!this.encryptionRequired || this._tenantEncryptionActive.has(tenantDid))) {
       return;
     }
 
@@ -237,27 +253,37 @@ export class DwnDataStore<TStoreObject extends Record<string, any> = Jwk> implem
       throw new Error(`Failed to query for protocols: ${status.code} - ${status.detail}`);
     }
 
+    let encryptionActive = false;
+
     if (entries?.length === 0) {
       // protocol is not installed, install it
-      await this.installProtocol(tenantDid, agent);
-    } else if (this.encryptionRequired && !this._tenantEncryptionActive.has(tenantDid)) {
+      const installed = await this.installProtocol(tenantDid, agent);
+      encryptionActive = installed.encryptionActive;
+    } else if (this.encryptionRequired) {
       // Protocol already installed — determine if it has $encryption keys
       // by inspecting the installed definition.
       const definition = entries![0].descriptor?.definition;
       const firstType = Object.keys(definition?.structure ?? {})[0];
-      const hasEncryption = !!(firstType && definition?.structure[firstType]?.$encryption);
-      this._tenantEncryptionActive.set(tenantDid, hasEncryption);
+      encryptionActive = !!(firstType && definition?.structure[firstType]?.$encryption);
     }
 
+    // Set both caches atomically so they always expire together. This
+    // prevents a stale-encryption window where one cache expires before
+    // the other and initialize() short-circuits on the surviving entry.
+    this._tenantEncryptionActive.set(tenantDid, encryptionActive);
     this._protocolInitializedCache.set(tenantDid, true);
   }
 
   /**
    * Returns `true` if any type in the protocol definition has `encryptionRequired: true`.
+   * Cached after first computation since the protocol definition is immutable.
    */
   private get encryptionRequired(): boolean {
-    return Object.values(this._recordProtocolDefinition.types)
-      .some((type): boolean => type.encryptionRequired === true);
+    if (this._encryptionRequired === undefined) {
+      this._encryptionRequired = Object.values(this._recordProtocolDefinition.types)
+        .some((type): boolean => type.encryptionRequired === true);
+    }
+    return this._encryptionRequired;
   }
 
   /**
@@ -328,7 +354,7 @@ export class DwnDataStore<TStoreObject extends Record<string, any> = Jwk> implem
    * If the tenant DID lacks an X25519 keyAgreement key, the error propagates
    * — plaintext fallback is not allowed.
    */
-  private async installProtocol(tenant: string, agent: EnboxPlatformAgent): Promise<void> {
+  private async installProtocol(tenant: string, agent: EnboxPlatformAgent): Promise<{ encryptionActive: boolean }> {
     let definition = this._recordProtocolDefinition;
     let encryptionActive = false;
 
@@ -342,8 +368,6 @@ export class DwnDataStore<TStoreObject extends Record<string, any> = Jwk> implem
       encryptionActive = true;
     }
 
-    this._tenantEncryptionActive.set(tenant, encryptionActive);
-
     const { reply : { status } } = await agent.dwn.processRequest({
       author        : tenant,
       target        : tenant,
@@ -354,6 +378,8 @@ export class DwnDataStore<TStoreObject extends Record<string, any> = Jwk> implem
     if (status.code !== 202) {
       throw new Error(`Failed to install protocol: ${status.code} - ${status.detail}`);
     }
+
+    return { encryptionActive };
   }
 
   private async lookupRecordId({ id, tenantDid, agent }: {
@@ -403,7 +429,7 @@ export class InMemoryDataStore<TStoreObject extends Record<string, any> = Jwk> i
   /**
    * A private field that contains the Map used as the in-memory data store.
    */
-  private store: Map<string, TStoreObject> = new Map();
+  private readonly store: Map<string, TStoreObject> = new Map();
 
   public async delete({ id, agent, tenant }: DataStoreDeleteParams): Promise<boolean> {
     // Determine the tenant identifier (DID) for the delete operation.

package/src/sync-closure-resolver.ts

@@ -366,7 +366,7 @@ function extractProtocolAwareDeps(
           Buffer.from(payload, 'base64url').toString('utf-8')
         );
         const protocolRole = decoded.protocolRole as string | undefined;
-        if (protocolRole && protocolRole.includes(':')) {
+        if (protocolRole?.includes(':')) {
           // Cross-protocol role: "alias:protocolPath"
           const roleColonIdx = protocolRole.indexOf(':');
           const roleAlias = protocolRole.substring(0, roleColonIdx);
@@ -518,7 +518,7 @@ export async function evaluateClosure(
       const currentProtocol = currentDesc.protocol as string | undefined;
       if (currentProtocol) {
         const cachedProtocolMsg = context.protocolCache.get(currentProtocol);
-        const protocolDef = (cachedProtocolMsg?.descriptor as any)?.definition;
+        const protocolDef = cachedProtocolMsg?.descriptor?.definition;
         if (protocolDef) {
           const protoAwareEdges = extractProtocolAwareDeps(current, protocolDef, context.isDelegateSession);
           const protoResult = await resolveEdges(