@keyhive/keyhive 0.1.0-alpha.4 → 0.1.0-alpha.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keyhive/keyhive",
-  "version": "0.1.0-alpha.4",
+  "version": "0.1.0-alpha.6",
   "description": "",
   "main": "pkg/keyhive_wasm.js",
   "keywords": [],

package/pkg/keyhive_wasm.d.ts

@@ -5,18 +5,56 @@ export class Access {
     private constructor();
     free(): void;
     [Symbol.dispose](): void;
+    /**
+     * The ability to revoke any members of a group, not just those that they have causal senority over.
+     */
+    static admin(): Access;
+    /**
+     * True if this level is at least as permissive as `other`.
+     */
+    atLeast(other: Access): boolean;
+    /**
+     * Standard comparator result: -1 if less permissive than `other`,
+     * 0 if equal, 1 if more permissive.
+     */
+    compareTo(other: Access): number;
+    /**
+     * The ability to edit (append ops to) the content of a document.
+     */
+    static edit(): Access;
+    equals(other: Access): boolean;
+    /**
+     * Parse an access level, throwing on invalid input.
+     * Accepts "relay", "read", "edit", or "admin" (case-insensitive).
+     */
+    static fromString(s: string): Access;
+    /**
+     * The ability to read (decrypt) the content of a document.
+     */
+    static read(): Access;
+    /**
+     * The ability to retrieve bytes over the network.
+     */
+    static relay(): Access;
     toString(): string;
+    /**
+     * Parse an access level, returning undefined on invalid input.
+     * Prefer `fromString`, which throws a descriptive error instead.
+     */
     static tryFromString(s: string): Access | undefined;
-}
-
-/**
- * The result of adding a member: the membership delegation.
- */
-export class AddMemberUpdate {
-    private constructor();
-    free(): void;
-    [Symbol.dispose](): void;
-    readonly delegation: SignedDelegation;
+    /**
+     * True for Edit access or higher.
+     */
+    readonly isEditor: boolean;
+    /**
+     * True for Read access or higher.
+     */
+    readonly isReader: boolean;
+    /**
+     * Numeric level for ordering: Relay = 0, Read = 1, Edit = 2, Admin = 3.
+     * Higher levels imply all lower levels.
+     */
+    readonly level: number;
 }
 
 export class Agent {
@@ -127,16 +165,14 @@ export class ContactCard {
 
 /**
  * Plaintext plus the application secret key that decrypted it.
- *
- * The key lets the consumer recover the blob's external predecessor-secret
- * chain and chain further encryptions onto it, without re-entering CGKA.
  */
-export class DecryptedWithKey {
+export class DecryptedKeyed {
     private constructor();
     free(): void;
     [Symbol.dispose](): void;
     /**
      * The 32-byte application secret key used to decrypt this content.
+     * Treat as secret: do not log or persist unencrypted.
      */
     readonly applicationSecret: Uint8Array;
     readonly plaintext: Uint8Array;
@@ -192,8 +228,7 @@ export class Encrypted {
     [Symbol.dispose](): void;
     /**
      * Decrypt this content with an explicit 32-byte application secret key,
-     * bypassing CGKA. The consumer uses this to follow the external
-     * predecessor-secret chain once it has recovered a blob's key.
+     * bypassing CGKA.
      */
     decryptWithKey(key: Uint8Array): Uint8Array;
     static fromBytes(bytes: Uint8Array): Encrypted;
@@ -212,11 +247,20 @@ export class EncryptedContentWithUpdate {
     [Symbol.dispose](): void;
     encrypted_content(): Encrypted;
     update_op(): SignedCgkaOperation | undefined;
+}
+
+/**
+ * Encrypted content plus the application secret key it was encrypted under.
+ */
+export class EncryptedKeyed {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    encrypted_content(): Encrypted;
+    update_op(): SignedCgkaOperation | undefined;
     /**
      * The 32-byte application secret key used to encrypt this content.
-     *
-     * Lets the consumer build the external predecessor-secret chain and chain
-     * further encryptions onto this blob.
+     * Treat as secret: do not log or persist unencrypted.
      */
     readonly applicationSecret: Uint8Array;
 }
@@ -313,12 +357,18 @@ export class Keyhive {
     free(): void;
     [Symbol.dispose](): void;
     accessForDoc(id: Identifier, doc_id: DocumentId): Promise<Access | undefined>;
-    addMember(to_add: Agent, membered: Membered, access: Access, other_relevant_docs: Document[]): Promise<AddMemberUpdate>;
+    addMember(to_add: Agent, membered: Membered, access: Access, other_relevant_docs: Document[]): Promise<SignedDelegation>;
     /**
      * Returns all agent events with deduplicated storage and two-tier indirection
      * for membership, prekey, and CGKA ops.
      */
     allAgentEvents(): Promise<AllAgentEvents>;
+    /**
+     * The most permissive of `id`'s direct access and the document's
+     * public access. Returns undefined if neither grants access (or the
+     * document is unknown).
+     */
+    bestAccessForDoc(id: Identifier, doc_id: DocumentId): Promise<Access | undefined>;
     contactCard(): Promise<ContactCard>;
     docMemberCapabilities(doc_id: DocumentId): Promise<Membership[]>;
     /**
@@ -334,14 +384,10 @@ export class Keyhive {
     /**
      * Force a PCS key rotation and return the new leaf secret, serialized as a
      * one-entry `BTreeMap<ShareKey, ShareSecretKey>` (the exact format
-     * `importPrekeySecrets` accepts). A sibling instance of this identity can
-     * install it to derive the rotated key without re-importing the whole bundle.
+     * `importPrekeySecrets` accepts).
+     * The returned bytes are secret key material: do not log or persist unencrypted.
      */
     forcePcsUpdate(doc: Document): Promise<Uint8Array>;
-    /**
-     * Generate a document. Whether it provides forward secrecy is determined by
-     * this peer's forward-secrecy policy (chosen at `Keyhive.init`).
-     */
     generateDocument(coparents: Peer[], initial_content_ref_head: ChangeId, more_initial_content_refs: ChangeId[]): Promise<Document>;
     generateGroup(js_coparents: Peer[]): Promise<Group>;
     getAgent(id: Identifier): Promise<Agent | undefined>;
@@ -352,9 +398,6 @@ export class Keyhive {
     importPrekeySecrets(bytes: Uint8Array): Promise<void>;
     ingestArchive(archive: Archive): Promise<void>;
     ingestEventsBytes(events_bytes_array: Array<any>): Promise<Array<any>>;
-    /**
-     * Initialize a peer.
-     */
     static init(signer: Signer, ciphertext_store: CiphertextStore, event_handler: Function): Promise<Keyhive>;
     intoArchive(): Promise<Archive>;
     membershipOpsForAgent(agent: Agent): Promise<Map<any, any>>;
@@ -369,13 +412,15 @@ export class Keyhive {
     tryDecrypt(doc: Document, encrypted: Encrypted): Promise<Uint8Array>;
     /**
      * Decrypt content and also return the 32-byte application secret key used.
-     *
-     * The consumer follows the external predecessor-secret chain from this key
-     * with `Encrypted.decryptWithKey`, avoiding further CGKA dives.
      */
-    tryDecryptWithKey(doc: Document, encrypted: Encrypted): Promise<DecryptedWithKey>;
+    tryDecryptKeyed(doc: Document, encrypted: Encrypted): Promise<DecryptedKeyed>;
     tryEncrypt(doc: Document, content_ref: ChangeId, js_pred_refs: ChangeId[], content: Uint8Array): Promise<EncryptedContentWithUpdate>;
     tryEncryptArchive(doc: Document, content_ref: ChangeId, pred_refs: ChangeId[], content: Uint8Array): Promise<EncryptedContentWithUpdate>;
+    /**
+     * Encrypt content and also return the application secret key it was
+     * encrypted under.
+     */
+    tryEncryptKeyed(doc: Document, content_ref: ChangeId, js_pred_refs: ChangeId[], content: Uint8Array): Promise<EncryptedKeyed>;
     tryPcsKeyHash(doc: Document): Promise<Uint8Array | undefined>;
     trySign(data: Uint8Array): Promise<Signed>;
     readonly id: IndividualId;
@@ -542,12 +587,6 @@ export function setPanicHook(): void;
 export function symmetricDecrypt(key: Uint8Array, blob: Uint8Array): Uint8Array;
 
 /**
- * AEAD-encrypt `plaintext` under a 32-byte `key`.
- *
- * `associated_data` flavors the synthetic nonce (e.g. the document or content
- * id) so identical plaintext under the same key in different contexts produces
- * distinct ciphertext. Returns `nonce(24) || ciphertext` (the ciphertext
- * includes the Poly1305 tag). The nonce is carried in the output, so
- * [`symmetric_decrypt`] does not need the associated data.
+ * Encrypt `plaintext` under a 32-byte `key`, returning `nonce(24) || ciphertext`.
  */
 export function symmetricEncrypt(key: Uint8Array, plaintext: Uint8Array, associated_data: Uint8Array): Uint8Array;

package/pkg/keyhive_wasm.js

@@ -5,5 +5,5 @@ import { __wbg_set_wasm } from "./keyhive_wasm_bg.js";
 __wbg_set_wasm(wasm);
 wasm.__wbindgen_start();
 export {
-    Access, AddMemberUpdate, Agent, AllAgentEvents, Archive, CannotParseEd25519SigningKey, CannotParseIdentifier, Capability, CgkaOperation, ChangeId, CiphertextStore, ContactCard, DecryptedWithKey, Delegation, DocContentRefs, Document, DocumentId, Encrypted, EncryptedContentWithUpdate, Event, GenerateWebCryptoError, Group, GroupId, History, Identifier, Individual, IndividualId, Invocation, Keyhive, Membered, Membership, Peer, Revocation, ShareKey, Signed, SignedCgkaOperation, SignedDelegation, SignedInvocation, SignedRevocation, Signer, Stats, Summary, setPanicHook, symmetricDecrypt, symmetricEncrypt
+    Access, Agent, AllAgentEvents, Archive, CannotParseEd25519SigningKey, CannotParseIdentifier, Capability, CgkaOperation, ChangeId, CiphertextStore, ContactCard, DecryptedKeyed, Delegation, DocContentRefs, Document, DocumentId, Encrypted, EncryptedContentWithUpdate, EncryptedKeyed, Event, GenerateWebCryptoError, Group, GroupId, History, Identifier, Individual, IndividualId, Invocation, Keyhive, Membered, Membership, Peer, Revocation, ShareKey, Signed, SignedCgkaOperation, SignedDelegation, SignedInvocation, SignedRevocation, Signer, Stats, Summary, setPanicHook, symmetricDecrypt, symmetricEncrypt
 } from "./keyhive_wasm_bg.js";