@atlastodo/client-core 0.1.13 → 0.1.14-rc.1

package/dist/api.d.ts

@@ -1,31 +1,22 @@
 /** Typed HTTP client: auth, key distribution, membership, reports, admin and `/sync/*`. A 401 rotates the refresh token once. */
 import type { AdminAuditEntry, AdminInviteView, AdminSettingsView, AdminUserView, AuthResponse, AuthUser, BugReportPayload, BugReportSummary, BugReportView, InviteView, MemberRole, MemberView, MissingProjectKey, PendingKeyRotation, Operation, ProjectKeysResponse, RecoverAccountPayload, RecoveryKeysResponse, RegisterRecoveryKeyPayload, ReplaceRecoveryKeyPayload, SaltResponse, SessionView, ApiTokenView, ApiTokenSessionResponse, CreateApiTokenPayload, UserPublicKeyResponse, SigningKeyResponse, ChangePasswordPayload, AppKeyRow, MigrateRootKeyPayload, PutRecoveryRootKeyPayload, RootKeyResponse, AccountProof, PasskeyAssertionResponse, PasskeyCreationOptions, PasskeyReauthResponse, PasskeyRegistrationPayload, PasskeyRequestOptions, PasskeyView } from "./types.js";
-import { Keyring, type EncryptedPayload, type PasswordKdf, type SealedKey, type WrappedProjectKey } from "./crypto/index.js";
+import { Keyring, type EncryptedPayload, type PasswordKdf, type SealedInvitePreview, type SealedKey, type WrappedProjectKey } from "./crypto/index.js";
 import { type ServerDiscovery } from "./discovery.js";
 import { type Repair, type ScopeStore } from "./scope.js";
-export type WireOp = {
-    id: string;
-    entity: Operation["entity"];
-    entity_id: string;
-    ts: {
-        wall_ms: number;
-        counter: number;
-        node: string;
-    };
-} & ({
-    op: "set";
-    field: string;
-    value: unknown;
-} | {
-    op: "delete";
-});
+import { type WireOp } from "./wire.js";
+import type { LegacyKeysPage } from "./legacy.js";
+export type { WireOp } from "./wire.js";
 /** Sync without an unlocked keyring would push plaintext or store ciphertext as content. Transient. */
 export declare class E2eeLockedError extends Error {
     constructor();
 }
 /** Explicit scope: `projectId`'s key (throws when not held) or the DEK when null; never falls back. */
 export declare function toEncryptedWire(op: Operation, keyring?: Keyring | null, projectId?: string | null): WireOp;
-/** `projectId` null is personal, undefined unknown (any held key may open). Unopened values stay envelopes. */
+/**
+ * One wire op, decoded on its own: a current one opened with the keys of its scope (still sealed
+ * without them), a legacy one by the protocol 6 rules, where `projectId` null is personal and
+ * undefined unknown (any held key may open). Throws for an op the decoder drops.
+ */
 export declare function fromEncryptedWire(w: WireOp, keyring?: Keyring | null, projectId?: string | null): Operation;
 type WireReport = {
     id: string;
@@ -148,6 +139,8 @@ export declare class ApiClient {
     /** Legacy migration done: plaintext in encrypted fields and v1 values are then dropped. Local, so the server cannot roll it back. */
     setLegacyMigrated(done: boolean): void;
     isLegacyMigrated(): boolean;
+    /** The real kind of an entity the attached store holds by this id. */
+    private kindOfEntity;
     private isCanonical;
     private unlockedKeyring;
     setTokens(token: string | undefined, refreshToken?: string): void;
@@ -385,10 +378,24 @@ export declare class ApiClient {
         from?: number;
         repairs: Repair[];
     };
+    /** The protocol 6 entities this partition still holds, a page at a time (`migrateLegacy`). */
+    legacyKeys(next?: string): Promise<LegacyKeysPage>;
+    /** Drop re-encoded protocol 6 entities from this partition; answers how many it still held. */
+    dropLegacy(keys: {
+        entity: string;
+        entity_id: string;
+    }[]): Promise<number>;
+    /**
+     * Whether this account may re-write every field of the entity: its own activity only (the server
+     * names the pusher as the actor), a shared project only as its owner (archive and delete are
+     * owner-only), a shared project's item only as an active member.
+     */
+    mayReencode(kind: Operation["entity"], entityId: string): boolean;
     /** WebSockets cannot set headers and proxies may log the URL, so it carries a single-use 30 s ticket, never the access token. */
     syncWsUrl(since: number): Promise<string | null>;
     listMembers(projectId: string): Promise<MemberView[]>;
-    inviteMember(projectId: string, email: string, role: MemberRole): Promise<MemberView>;
+    /** `preview`: what the invitee is shown before accepting (`sealInvitePreview`). */
+    inviteMember(projectId: string, email: string, role: MemberRole, preview?: SealedInvitePreview): Promise<MemberView>;
     acceptInvite(projectId: string): Promise<void>;
     declineInvite(projectId: string): Promise<void>;
     updateMemberRole(projectId: string, userId: string, role: MemberRole): Promise<MemberView>;
@@ -396,4 +403,3 @@ export declare class ApiClient {
     claimProjectOwnership(projectId: string): Promise<MemberView>;
     listInvites(): Promise<InviteView[]>;
 }
-export {};

package/dist/crypto/envelope.d.ts

@@ -48,16 +48,16 @@ export declare function unwrapAttachmentKey(wrapped: WrappedAttachmentKey, key:
  */
 export declare function isWrappedAttachmentKey(v: unknown): v is WrappedAttachmentKey;
 /**
- * Whether a field value is still in encrypted wire form (`{ __enc: 2, kid, iv, ct }` or older
- * `__enc: 1`). A field no key here opens is stored as this object, so its presence means
- * "unreadable here", not "empty".
+ * Whether a field value is still in encrypted wire form (`{ __enc: 3, kid, iv, ct }`, or the older
+ * `__enc: 2` and `__enc: 1`). A field no key here opens is stored as this object, so its presence
+ * means "unreadable here", not "empty".
  */
 export declare function isEncryptedEnvelope(v: unknown): v is {
     __enc: 1;
     iv: string;
     ct: string;
 } | {
-    __enc: 2;
+    __enc: 2 | 3;
     kid: string;
     iv: string;
     ct: string;

package/dist/crypto/field.d.ts

@@ -1,9 +1,12 @@
 /**
- * Field-value encryption: the `{ __enc: 2, kid, iv, ct }` envelope. The AES-GCM associated data binds
- * a value to its envelope version, entity kind and id, field name, key scope and key id, so
- * ciphertext the server copies elsewhere fails to open instead of being read or re-encrypted there.
- * The JSON plaintext is padded to a size bucket so length does not reveal `true` from `false` or a
- * short title from a long one. Version 1 (unpadded, no associated data) is read, never written.
+ * Field-value encryption. Version 3 (`sealField`, sync protocol 7) is what clients write: the
+ * plaintext holds the real kind and field name too, and the wire carries an opaque tag
+ * (`fieldTag`) instead of the field name. Version 2 (`{ __enc: 2, kid, iv, ct }`) is read for rows
+ * written before protocol 7. In both, the AES-GCM associated data binds a value to its envelope
+ * version, wire kind and entity id, wire field, key scope and key id, so ciphertext the server
+ * copies elsewhere fails to open instead of being read or re-encrypted there. Both pad the JSON
+ * plaintext to a size bucket so length does not reveal `true` from `false` or a short title from a
+ * long one. Version 1 (unpadded, no associated data) is read, never written.
  */
 export declare const FIELD_ENVELOPE_VERSION = 2;
 export type KeyScope = {
@@ -26,12 +29,12 @@ export interface FieldEnvelopeV2 {
 export declare function sameKeyScope(a: KeyScope, b: KeyScope): boolean;
 export declare function keyScopeLabel(scope: KeyScope): string;
 /**
- * The padded size for `n` bytes of plaintext plus the one-byte pad marker: at least 32, then the
- * next power of two up to 1 KiB, then the next multiple of 1 KiB.
+ * The padded size for `n` bytes of plaintext plus the one-byte pad marker: at least `min` (32 for
+ * version 2), then the next power of two up to 1 KiB, then the next multiple of 1 KiB.
  */
-export declare function paddedLength(n: number): number;
+export declare function paddedLength(n: number, min?: number): number;
 /** Append 0x80 and zeros up to the bucket size (ISO/IEC 7816-4 padding). */
-export declare function padPlaintext(data: Uint8Array): Uint8Array;
+export declare function padPlaintext(data: Uint8Array, min?: number): Uint8Array;
 export declare function unpadPlaintext(data: Uint8Array): Uint8Array;
 export declare function encryptField(key: Uint8Array, kid: string, scope: KeyScope, at: FieldLocation, value: unknown): FieldEnvelopeV2;
 /**
@@ -39,4 +42,44 @@ export declare function encryptField(key: Uint8Array, kid: string, scope: KeySco
  * when any of that is untrue: another key, another scope, or a value copied from elsewhere.
  */
 export declare function decryptField(key: Uint8Array, scope: KeyScope, at: FieldLocation, envelope: FieldEnvelopeV2): unknown;
+/** Sync protocol 7's envelope (docs/decisions/0006). */
+export declare const FIELD_ENVELOPE_V3 = 3;
+/**
+ * A v3 plaintext carries the kind and field name too, so its smallest bucket is 64 bytes: a small
+ * value of a long-named field must not fall in another bucket than one of a short-named field.
+ */
+export declare const FIELD_V3_MIN_PADDING = 64;
+export interface FieldEnvelopeV3 {
+    __enc: 3;
+    kid: string;
+    iv: string;
+    ct: string;
+}
+/** Where a v3 envelope sits on the wire: the wire kind and wire field (a tag or a public name). */
+export interface WireLocation {
+    entity: string;
+    entityId: string;
+    field: string;
+}
+/** What a v3 envelope holds. */
+export interface SealedField {
+    kind: string;
+    field: string;
+    value: unknown;
+}
+export declare function sealField(key: Uint8Array, kid: string, scope: KeyScope, at: WireLocation, sealed: SealedField): FieldEnvelopeV3;
+/**
+ * Open a v3 envelope that claims to sit at `at` under `key` of `scope`. Throws when any of that is
+ * untrue, or when the plaintext is not a `[kind, field, value]` triple.
+ */
+export declare function openSealedField(key: Uint8Array, scope: KeyScope, at: WireLocation, envelope: FieldEnvelopeV3): SealedField;
+export declare function isFieldEnvelopeV3(v: unknown): v is FieldEnvelopeV3;
+/** The key a scope's field tags are made with: HKDF-SHA256 of the encrypting key. */
+export declare function fieldTagKey(key: Uint8Array): Uint8Array;
+/**
+ * The opaque wire name of `field` of `kind` entity `entityId`: 32 lowercase hex digits. The entity
+ * id is part of it, so the same field of two entities has unrelated tags.
+ */
+export declare function fieldTag(tagKey: Uint8Array, entityId: string, kind: string, field: string): string;
+export declare function isFieldTag(name: string): boolean;
 export declare function isFieldEnvelopeV2(v: unknown): v is FieldEnvelopeV2;

package/dist/crypto/index.d.ts

@@ -11,3 +11,4 @@ export * from "./blob.js";
 export * from "./apiToken.js";
 export * from "./rootKey.js";
 export * from "./passkey.js";
+export * from "./invitePreview.js";

package/dist/crypto/invitePreview.d.ts

@@ -0,0 +1,23 @@
+/**
+ * What an invitee is shown before accepting (sync protocol 7): the project's name, icon, color and
+ * kind, which the server cannot read any more, encrypted by the inviter under the project key the
+ * invitee receives sealed with the invite. Bound to the project and the key id, and padded like a
+ * field value, so the server can neither move it to another project nor learn the name's length.
+ */
+export interface InvitePreview {
+    name?: unknown;
+    icon?: unknown;
+    color?: unknown;
+    kind?: unknown;
+}
+export interface SealedInvitePreview {
+    v: 1;
+    kid: string;
+    iv: string;
+    ct: string;
+}
+/** Under project key `pek` (id `kid`) of `projectId`. */
+export declare function sealInvitePreview(pek: Uint8Array, kid: string, projectId: string, preview: InvitePreview): SealedInvitePreview;
+/** Throws unless `pek` sealed it for `projectId`. */
+export declare function openInvitePreview(pek: Uint8Array, projectId: string, sealed: SealedInvitePreview): InvitePreview;
+export declare function isSealedInvitePreview(v: unknown): v is SealedInvitePreview;

package/dist/fieldPolicy.d.ts

@@ -1,10 +1,13 @@
 /**
- * Which field values leave the device in plaintext. Everything else, including fields nothing
- * declares yet, is end-to-end encrypted, so a new field cannot leak because a list was forgotten.
+ * What of an entity leaves the device readable (sync protocol 7, docs/decisions/0006): the wire
+ * kind it travels as instead of its real kind, the few field names that travel as they are instead
+ * of an opaque tag (`public_fields`), and which of those carry a plaintext value
+ * (`plaintext_fields`). Everything else, including fields nothing declares yet, travels under a
+ * tag in an encrypted value, so a new field cannot leak because a list was forgotten.
  *
- * The table is the `plaintext_fields` of each kind in the bundled app manifests
- * (`manifests/<app>.json`), which the server compiles in too and checks every field value it
- * reads against.
+ * The tables are the bundled app manifests (`manifests/<app>.json`), which the server compiles in
+ * too. `legacy_plaintext_fields` is what protocol 6 sent unencrypted, which reading the rows
+ * written before protocol 7 needs.
  */
 import type { EntityKind } from "./types.js";
 /**
@@ -22,13 +25,18 @@ export interface TokenPolicy {
     exclusive: boolean;
 }
 /** A bundled app manifest: its id, version, the entity kinds it syncs and its token policy. */
+export interface KindManifest {
+    /** The kind the server sees. */
+    wire: string;
+    public_fields?: readonly string[];
+    plaintext_fields?: readonly string[] | "all";
+    legacy_plaintext_fields?: readonly string[];
+}
 export interface AppManifest {
     app: string;
     name: string;
     version: number;
-    kinds: Record<string, {
-        plaintext_fields: readonly string[] | "all";
-    }>;
+    kinds: Record<string, KindManifest>;
     api_tokens?: Partial<TokenPolicy>;
 }
 /**
@@ -47,10 +55,29 @@ export declare const BUNDLED_MANIFESTS: readonly AppManifest[];
 export declare function tokenPolicyFor(apps: readonly string[]): TokenPolicy;
 /** The bundled app owning the kind with this wire name, if any. */
 export declare function appOfKind(kind: string): AppManifest | undefined;
+/** Per real kind, the fields whose value travels unencrypted. */
 export declare const PLAINTEXT_FIELDS: Readonly<Record<EntityKind, readonly string[] | "all">>;
 /**
- * Whether a value of `entity`.`field` is end-to-end encrypted, for any wire kind: a kind no
- * bundled manifest names encrypts everything.
+ * The app owning wire name `name`: a wire kind (`todo.sealed`), or a real kind name, which rows
+ * written before protocol 7 carry.
  */
+export declare function appOfWire(name: string): AppManifest | undefined;
+/** The wire kind `kind` travels as; null for a kind no bundled manifest names. */
+export declare function wireKindOf(kind: string): string | null;
+/** Whether `field` of `kind` goes on the wire under its name rather than an opaque tag. */
+export declare function isPublicField(kind: string, field: string): boolean;
+/** Whether a value of `kind`.`field` leaves the device encrypted (protocol 7). */
 export declare function shouldEncryptKindField(entity: string, field: string): boolean;
 export declare function shouldEncryptField(entity: EntityKind, field: string): boolean;
+/** Whether protocol 6 encrypted a value of `kind`.`field`: how a legacy row is read. */
+export declare function legacyEncrypted(kind: string, field: string): boolean;
+/** Whether `name` is the wire kind of rows written before protocol 7: a real kind that now
+ * travels as another. */
+export declare function isLegacyWireKind(name: string): boolean;
+/** The real kinds that travel as wire kind `wire`. */
+export declare function kindsOfWire(wire: string): EntityKind[];
+/**
+ * The real kind a public field names on wire kind `wire` (`blob_sha` on `todo.sealed` is an
+ * attachment's), or the wire kind's only real kind; null when neither tells.
+ */
+export declare function realKindOf(wire: string, publicField?: string): EntityKind | null;

package/dist/index.d.ts

@@ -20,6 +20,8 @@ export * from "./attachments.js";
 export * from "./indexeddb.js";
 export * from "./expo-sqlite.js";
 export * from "./sync-client.js";
+export * from "./wire.js";
+export * from "./legacy.js";
 export * from "./realtime.js";
 export * from "./session.js";
 export * from "./password.js";