@membox-cloud/membox 0.1.0

package/dist/src/cli/unlock.js

@@ -0,0 +1,153 @@
+import { readState } from "../store/local-state.js";
+import { getBytes, ACCOUNTS } from "../store/keychain.js";
+import { deriveURK } from "../crypto/kdf.js";
+import { unwrapAMK } from "../crypto/keys.js";
+import { vaultSession } from "../store/session.js";
+import { disableManagedUnlock, enableManagedUnlock, getManagedUnlockPassphrase, getManagedUnlockStatus, } from "../store/managed-unlock.js";
+import { readPassphrase } from "./passphrase-input.js";
+async function canUnlockVault() {
+    const state = await readState();
+    if (!state?.setup_complete) {
+        return false;
+    }
+    const wrappedAmk = await getBytes(ACCOUNTS.WRAPPED_AMK);
+    const salt = await getBytes(ACCOUNTS.WRAPPED_AMK_SALT);
+    const iv = await getBytes(ACCOUNTS.WRAPPED_AMK_IV);
+    const tag = await getBytes(ACCOUNTS.WRAPPED_AMK_TAG);
+    if (!wrappedAmk || !salt || !iv || !tag) {
+        return false;
+    }
+    return true;
+}
+export async function unlockWithPassphrase(passphrase, options) {
+    const state = await readState();
+    if (!state?.setup_complete) {
+        if (options?.announceFailure) {
+            console.log("Vault not set up. Run `openclaw membox setup`.");
+        }
+        return false;
+    }
+    const wrappedAmk = await getBytes(ACCOUNTS.WRAPPED_AMK);
+    const salt = await getBytes(ACCOUNTS.WRAPPED_AMK_SALT);
+    const iv = await getBytes(ACCOUNTS.WRAPPED_AMK_IV);
+    const tag = await getBytes(ACCOUNTS.WRAPPED_AMK_TAG);
+    if (!wrappedAmk || !salt || !iv || !tag) {
+        if (options?.announceFailure) {
+            console.error("Keychain data missing. Re-run setup or use recovery.");
+        }
+        return false;
+    }
+    if (options?.announceDeriving) {
+        console.log("Deriving key...");
+    }
+    const { urk } = await deriveURK(passphrase, salt);
+    try {
+        const amk = unwrapAMK(urk, { encrypted_amk: wrappedAmk, iv, tag });
+        vaultSession.unlock(amk);
+        if (options?.announceSuccess) {
+            console.log("Vault unlocked.");
+        }
+        return true;
+    }
+    catch {
+        if (options?.announceFailure) {
+            console.error("Wrong passphrase.");
+        }
+        return false;
+    }
+    finally {
+        urk.fill(0);
+    }
+}
+export async function tryManagedUnlock(options) {
+    const passphrase = await getManagedUnlockPassphrase();
+    if (!passphrase) {
+        return false;
+    }
+    const unlocked = await unlockWithPassphrase(passphrase, {
+        announceDeriving: options?.announceDeriving,
+        announceSuccess: false,
+        announceFailure: false,
+    });
+    if (unlocked) {
+        if (options?.announceSuccess) {
+            console.log("Vault unlocked from the managed local unlock secret.");
+        }
+        return true;
+    }
+    if (options?.announceFailure) {
+        console.error("Managed unlock secret failed. Disable it and re-enable it with the current passphrase.");
+    }
+    return false;
+}
+export async function ensureVaultUnlocked(options) {
+    if (vaultSession.isUnlocked()) {
+        if (options?.announceAlreadyUnlocked) {
+            console.log("Vault is already unlocked.");
+        }
+        return true;
+    }
+    if (!(await canUnlockVault())) {
+        const state = await readState();
+        if (!state?.setup_complete) {
+            console.log("Vault not set up. Run `openclaw membox setup`.");
+        }
+        else {
+            console.error("Keychain data missing. Re-run setup or use recovery.");
+        }
+        return false;
+    }
+    if (options?.allowManagedUnlock !== false) {
+        const managedStatus = await getManagedUnlockStatus();
+        if (managedStatus.enabled) {
+            const unlocked = await tryManagedUnlock({
+                announceDeriving: true,
+                announceSuccess: options?.announceSuccess,
+                announceFailure: options?.allowPrompt !== false,
+            });
+            if (unlocked) {
+                return true;
+            }
+            if (options?.allowPrompt === false) {
+                return false;
+            }
+            if (!managedStatus.secret_present) {
+                console.error("Managed unlock is enabled but no local unlock secret is stored.");
+            }
+            else {
+                console.log("Falling back to a manual passphrase prompt.");
+            }
+        }
+    }
+    if (options?.allowPrompt === false) {
+        return false;
+    }
+    const passphrase = await readPassphrase("Vault passphrase: ");
+    return unlockWithPassphrase(passphrase, {
+        announceDeriving: true,
+        announceFailure: true,
+        announceSuccess: options?.announceSuccess,
+    });
+}
+export async function unlockAction() {
+    await ensureVaultUnlocked({
+        announceAlreadyUnlocked: true,
+        announceSuccess: true,
+    });
+}
+export async function enableManagedUnlockAction(passphrase) {
+    const unlocked = await unlockWithPassphrase(passphrase, {
+        announceDeriving: true,
+        announceFailure: true,
+        announceSuccess: false,
+    });
+    if (!unlocked) {
+        throw new Error("Wrong passphrase. Managed unlock secret was not enabled.");
+    }
+    await enableManagedUnlock(passphrase);
+    console.log("Managed unlock secret enabled on this machine.");
+}
+export async function disableManagedUnlockAction() {
+    await disableManagedUnlock();
+    console.log("Managed unlock secret disabled on this machine.");
+}

package/dist/src/config.d.ts

@@ -0,0 +1,4 @@
+export interface memboxConfig {
+    serverUrl: string;
+}
+export declare function resolveConfig(raw: unknown): memboxConfig;

package/dist/src/config.js

@@ -0,0 +1,12 @@
+import { DEFAULT_SERVER_URL } from "./constants.js";
+export function resolveConfig(raw) {
+    const obj = raw && typeof raw === "object" ? raw : {};
+    // Priority: MEMBOX_SERVER_URL env var > plugin config > default
+    const envUrl = process.env.MEMBOX_SERVER_URL;
+    const serverUrl = typeof envUrl === "string" && envUrl.length > 0
+        ? envUrl
+        : typeof obj.serverUrl === "string"
+            ? obj.serverUrl
+            : DEFAULT_SERVER_URL;
+    return { serverUrl };
+}

package/dist/src/constants.d.ts

@@ -0,0 +1,23 @@
+export declare const PLUGIN_ID = "membox";
+export declare const PLUGIN_VERSION = "0.1.0";
+export declare const DEFAULT_SERVER_URL = "https://membox.cloud";
+export declare const API_PREFIX = "/api/v1";
+export declare const KEYCHAIN_SERVICE: string;
+export declare const STATE_DIR = ".membox";
+export declare const STATE_FILE = "state.json";
+export declare const PENDING_SETUP_FILE = "pending-setup.json";
+export declare const STATE_ROOT_ENV = "MEMBOX_STATE_ROOT";
+export declare function resolveStateRoot(): string;
+export declare const MANIFEST_VERSION = 1;
+export declare const CIPHER_ALGORITHM: "aes-256-gcm";
+export declare const WRAP_ALGORITHM: "aes-256-gcm";
+export declare const CRYPTO_VERSION = 1;
+export declare const ARGON2_PARAMS: {
+    readonly memoryKib: 65536;
+    readonly iterations: 3;
+    readonly parallelism: 4;
+    readonly saltLength: 16;
+    readonly outputLength: 32;
+};
+export declare const MEMORY_ROOT_PATH = "MEMORY.md";
+export declare const MEMORY_DAILY_PATTERN: RegExp;

package/dist/src/constants.js

@@ -0,0 +1,27 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+export const PLUGIN_ID = "membox";
+export const PLUGIN_VERSION = "0.1.0";
+export const DEFAULT_SERVER_URL = "https://membox.cloud";
+export const API_PREFIX = "/api/v1";
+export const KEYCHAIN_SERVICE = process.env.MEMBOX_KEYCHAIN_SERVICE || "membox.cloud";
+export const STATE_DIR = ".membox";
+export const STATE_FILE = "state.json";
+export const PENDING_SETUP_FILE = "pending-setup.json";
+export const STATE_ROOT_ENV = "MEMBOX_STATE_ROOT";
+export function resolveStateRoot() {
+    return process.env[STATE_ROOT_ENV] || join(homedir(), STATE_DIR);
+}
+export const MANIFEST_VERSION = 1;
+export const CIPHER_ALGORITHM = "aes-256-gcm";
+export const WRAP_ALGORITHM = "aes-256-gcm";
+export const CRYPTO_VERSION = 1;
+export const ARGON2_PARAMS = {
+    memoryKib: 65536,
+    iterations: 3,
+    parallelism: 4,
+    saltLength: 16,
+    outputLength: 32,
+};
+export const MEMORY_ROOT_PATH = "MEMORY.md";
+export const MEMORY_DAILY_PATTERN = /^memory\/\d{4}-\d{2}-\d{2}\.md$/;

package/dist/src/contract-types.d.ts

@@ -0,0 +1,301 @@
+export interface AadDescriptor {
+    user_id: string;
+    object_id: string;
+    object_version: number;
+    created_by_device_id: string;
+}
+export interface AccountMe {
+    user_id: string;
+    display_name: string | null;
+    primary_email: string | null;
+    providers: LinkedProviderOut[];
+    current_device_id?: string | null;
+}
+export interface BinaryDownloadResponse {
+    payload_b64: string;
+    content_sha256: string;
+}
+export interface BinaryUploadInput {
+    payload_b64: string;
+    content_sha256: string;
+}
+export interface BinaryUploadResponse {
+    blob_key: string;
+    content_sha256: string;
+    payload_size: number;
+}
+export interface BlobRef {
+    blob_key: string;
+    iv_b64: string;
+    tag_b64: string;
+}
+export interface ChangeItem {
+    seq: number;
+    object_id: string;
+    version: number;
+    change_type: string;
+    created_by_device_id: string;
+    created_at: string;
+}
+export interface DekEnvelope {
+    version?: number;
+    algorithm?: "aes-256-gcm";
+    wrapped_for?: "amk";
+    encrypted_dek_b64: string;
+    iv_b64: string;
+    tag_b64: string;
+}
+export interface DeviceGrantApproveInput {
+    encrypted_grant_payload_b64: string;
+    signature: DeviceGrantSignature;
+    payload_checksum_sha256: string;
+}
+export interface DeviceGrantOut {
+    grant_id: string;
+    source_device_id?: string | null;
+    target_device_id: string;
+    target_device_name?: string;
+    target_platform?: string;
+    status: "pending" | "approved" | "rejected" | "expired";
+    expires_at: string;
+    crypto_version?: number;
+    target_device_kex_public_key_b64?: string | null;
+    encrypted_grant_payload_b64?: string | null;
+    grant_signature_b64?: string | null;
+    signature_algorithm?: string | null;
+    source_device_sign_public_key_b64?: string | null;
+    source_device_kex_public_key_b64?: string | null;
+}
+export interface DeviceGrantSignature {
+    signature_algorithm?: "ed25519";
+    signature_b64: string;
+}
+export interface DevicePollResponse {
+    status: "authorization_pending" | "access_granted" | "slow_down" | "expired_token" | "denied";
+    access_token?: string | null;
+    refresh_token?: string | null;
+    token_type?: string | null;
+    expires_in?: number | null;
+    device_id?: string | null;
+}
+export interface DeviceStartRequest {
+    device_name: string;
+    platform: Platform;
+    plugin_version?: string | null;
+    sign_public_key_b64?: string | null;
+    kex_public_key_b64?: string | null;
+}
+export interface DeviceStartResponse {
+    device_code: string;
+    user_code: string;
+    verification_uri: string;
+    verification_uri_complete: string;
+    expires_in: number;
+    interval: number;
+}
+export interface DeviceSummary {
+    device_id: string;
+    device_name: string;
+    platform: Platform;
+    plugin_version?: string | null;
+    status: "active" | "revoked" | "pending";
+    created_at: string;
+    last_seen_at: string | null;
+    has_device_keys?: boolean;
+    grant_capable?: boolean;
+    is_current: boolean;
+}
+export interface DeviceVerifyDetail {
+    user_code: string;
+    device_name: string;
+    platform: Platform;
+    plugin_version: string | null;
+    status: "pending" | "confirmed" | "denied" | "expired" | "issued";
+    expires_at: string;
+}
+export interface EmailRequestInput {
+    email: string;
+}
+export interface EmailRequestResponse {
+    sent?: boolean;
+    debug_code?: string | null;
+}
+export interface EmailVerifyInput {
+    email: string;
+    code: string;
+}
+export interface EncryptedObjectManifest {
+    manifest_version?: number;
+    cipher_algorithm?: "aes-256-gcm" | "AES-256-GCM";
+    wrap_algorithm?: "aes-256-gcm" | "aes-256-kw" | "AES-256-GCM" | "AES-256-KW";
+    object_id: string;
+    object_version: number;
+    ciphertext_size: number;
+    content_sha256: string;
+    metadata_sha256: string;
+    blob: BlobRef;
+    metadata: BlobRef;
+    dek_envelope: DekEnvelope;
+    aad: AadDescriptor;
+}
+export interface ExportStatusResponse {
+    export_id: string;
+    status: "queued" | "running" | "done" | "failed" | "expired";
+    artifact_key: string | null;
+    expires_at: string | null;
+    created_at?: string | null;
+    completed_at?: string | null;
+    download_url?: string | null;
+}
+export interface GenericMessage {
+    ok?: boolean;
+    message?: string | null;
+}
+export interface HealthResponse {
+    status: string;
+}
+export interface LinkedProviderOut {
+    provider: Provider;
+    provider_email: string | null;
+    linked_at: string;
+    is_primary: boolean;
+}
+export interface ManifestResponse {
+    manifest: EncryptedObjectManifest;
+}
+export interface PendingDeviceAuthorization {
+    authorization_id: string;
+    user_code: string;
+    device_name: string;
+    platform: Platform;
+    plugin_version: string | null;
+    status: "pending";
+    created_at: string;
+    expires_at: string;
+}
+export type Platform = "macos" | "windows" | "linux" | "unknown";
+export type Provider = "github" | "google" | "email";
+export interface ProviderLinkInput {
+    code: string;
+    redirect_uri: string;
+}
+export interface ProviderStartResponse {
+    authorization_url: string;
+    provider: Provider;
+    flow: string;
+}
+export interface RecoveryBundleDownload {
+    material_type: string;
+    encrypted_payload_b64: string;
+    payload_checksum: string;
+    algorithm: string;
+    crypto_version: number;
+}
+export interface RecoveryDownloadInput {
+    material_type?: "recovery_bundle" | "recovery_code";
+}
+export interface RecoveryMaterialStatus {
+    has_recovery_code: boolean;
+    has_recovery_bundle: boolean;
+    updated_at: string | null;
+}
+export interface RecoveryMaterialUpload {
+    material_type: "recovery_bundle" | "recovery_code";
+    encrypted_payload_b64: string;
+    payload_checksum: string;
+    algorithm?: "aes-256-gcm";
+    crypto_version?: number;
+}
+export interface RefreshTokenInput {
+    refresh_token: string;
+}
+export interface SyncChangesResponse {
+    cursor: number;
+    changes: ChangeItem[];
+}
+export interface SyncCommitInput {
+    manifest: EncryptedObjectManifest;
+}
+export interface SyncCommitResponse {
+    object_id: string;
+    version: number;
+    seq: number;
+}
+export interface SyncStatusResponse {
+    cursor: number;
+    object_count: number;
+    current_device_last_seen_at: string | null;
+}
+export interface TokenResponse {
+    access_token: string;
+    refresh_token: string;
+    token_type?: string;
+    expires_in: number;
+    device_id: string;
+}
+export type LinkedProvider = LinkedProviderOut;
+export type DeviceGrant = DeviceGrantOut;
+export type ExportTask = ExportStatusResponse;
+export type ExportStatus = ExportTask["status"];
+export type SyncChange = ChangeItem;
+export type TokenPair = TokenResponse;
+export type EmailRequestPayload = EmailRequestInput;
+export type EmailVerifyPayload = EmailVerifyInput;
+export declare const ERROR_CODES: {
+    readonly UNAUTHORIZED: "unauthorized";
+    readonly FORBIDDEN: "forbidden";
+    readonly TOKEN_EXPIRED: "token_expired";
+    readonly REFRESH_TOKEN_INVALID: "refresh_token_invalid";
+    readonly EMAIL_RATE_LIMITED: "email_rate_limited";
+    readonly EMAIL_CODE_INVALID: "email_code_invalid";
+    readonly EMAIL_CODE_EXPIRED: "email_code_expired";
+    readonly DEVICE_CODE_EXPIRED: "device_code_expired";
+    readonly DEVICE_CODE_NOT_FOUND: "device_code_not_found";
+    readonly DEVICE_CODE_ALREADY_CONFIRMED: "device_code_already_confirmed";
+    readonly PROVIDER_ALREADY_LINKED: "provider_already_linked";
+    readonly PROVIDER_IS_PRIMARY: "provider_is_primary";
+    readonly LAST_PROVIDER: "last_provider";
+    readonly DEVICE_ALREADY_REVOKED: "device_already_revoked";
+    readonly CANNOT_REVOKE_CURRENT: "cannot_revoke_current";
+    readonly EXPORT_IN_PROGRESS: "export_in_progress";
+    readonly RECOVERY_REGENERATE_IN_PLUGIN: "recovery_regenerate_in_plugin";
+    readonly EXPIRED: "expired";
+    readonly PAYLOAD_TOO_LARGE: "payload_too_large";
+    readonly VALIDATION_ERROR: "validation_error";
+    readonly NOT_FOUND: "not_found";
+    readonly INTERNAL_ERROR: "internal_error";
+    readonly AAD_MISMATCH: "aad_mismatch";
+    readonly ACCESS_DENIED: "access_denied";
+    readonly ALREADY_DELETED: "already_deleted";
+    readonly BLOB_NOT_FOUND: "blob_not_found";
+    readonly CHECKSUM_MISMATCH: "checksum_mismatch";
+    readonly DEVICE_INACTIVE: "device_inactive";
+    readonly INVALID_AUTH: "invalid_auth";
+    readonly INVALID_DEVICE: "invalid_device";
+    readonly INVALID_FLOW: "invalid_flow";
+    readonly INVALID_OBJECT_ID: "invalid_object_id";
+    readonly INVALID_PAYLOAD: "invalid_payload";
+    readonly INVALID_SESSION: "invalid_session";
+    readonly INVALID_STATE: "invalid_state";
+    readonly INVALID_TOKEN: "invalid_token";
+    readonly OAUTH_FAILED: "oauth_failed";
+    readonly OBJECT_DELETED: "object_deleted";
+    readonly PROVIDER_NOT_CONFIGURED: "provider_not_configured";
+    readonly SESSION_EXPIRED: "session_expired";
+    readonly SESSION_MISMATCH: "session_mismatch";
+    readonly SESSION_REVOKED: "session_revoked";
+    readonly UNSUPPORTED_PROVIDER: "unsupported_provider";
+    readonly USER_INACTIVE: "user_inactive";
+    readonly VERSION_CONFLICT: "version_conflict";
+    readonly NO_SESSION: "no_session";
+    readonly EXPORT_NOT_READY: "export_not_ready";
+};
+export type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];
+export interface ApiErrorBody {
+    error: {
+        code: ErrorCode | string;
+        message: string;
+        request_id: string;
+        details?: Record<string, unknown>;
+    };
+}

package/dist/src/contract-types.js

@@ -0,0 +1,52 @@
+// Inlined from @membox/contract for standalone npm publishing.
+// Source: packages/contract/src/generated/types.ts + packages/contract/src/types.ts
+// ErrorCode and ApiErrorBody
+export const ERROR_CODES = {
+    UNAUTHORIZED: "unauthorized",
+    FORBIDDEN: "forbidden",
+    TOKEN_EXPIRED: "token_expired",
+    REFRESH_TOKEN_INVALID: "refresh_token_invalid",
+    EMAIL_RATE_LIMITED: "email_rate_limited",
+    EMAIL_CODE_INVALID: "email_code_invalid",
+    EMAIL_CODE_EXPIRED: "email_code_expired",
+    DEVICE_CODE_EXPIRED: "device_code_expired",
+    DEVICE_CODE_NOT_FOUND: "device_code_not_found",
+    DEVICE_CODE_ALREADY_CONFIRMED: "device_code_already_confirmed",
+    PROVIDER_ALREADY_LINKED: "provider_already_linked",
+    PROVIDER_IS_PRIMARY: "provider_is_primary",
+    LAST_PROVIDER: "last_provider",
+    DEVICE_ALREADY_REVOKED: "device_already_revoked",
+    CANNOT_REVOKE_CURRENT: "cannot_revoke_current",
+    EXPORT_IN_PROGRESS: "export_in_progress",
+    RECOVERY_REGENERATE_IN_PLUGIN: "recovery_regenerate_in_plugin",
+    EXPIRED: "expired",
+    PAYLOAD_TOO_LARGE: "payload_too_large",
+    VALIDATION_ERROR: "validation_error",
+    NOT_FOUND: "not_found",
+    INTERNAL_ERROR: "internal_error",
+    AAD_MISMATCH: "aad_mismatch",
+    ACCESS_DENIED: "access_denied",
+    ALREADY_DELETED: "already_deleted",
+    BLOB_NOT_FOUND: "blob_not_found",
+    CHECKSUM_MISMATCH: "checksum_mismatch",
+    DEVICE_INACTIVE: "device_inactive",
+    INVALID_AUTH: "invalid_auth",
+    INVALID_DEVICE: "invalid_device",
+    INVALID_FLOW: "invalid_flow",
+    INVALID_OBJECT_ID: "invalid_object_id",
+    INVALID_PAYLOAD: "invalid_payload",
+    INVALID_SESSION: "invalid_session",
+    INVALID_STATE: "invalid_state",
+    INVALID_TOKEN: "invalid_token",
+    OAUTH_FAILED: "oauth_failed",
+    OBJECT_DELETED: "object_deleted",
+    PROVIDER_NOT_CONFIGURED: "provider_not_configured",
+    SESSION_EXPIRED: "session_expired",
+    SESSION_MISMATCH: "session_mismatch",
+    SESSION_REVOKED: "session_revoked",
+    UNSUPPORTED_PROVIDER: "unsupported_provider",
+    USER_INACTIVE: "user_inactive",
+    VERSION_CONFLICT: "version_conflict",
+    NO_SESSION: "no_session",
+    EXPORT_NOT_READY: "export_not_ready",
+};

package/dist/src/crypto/aes-gcm.d.ts

@@ -0,0 +1,29 @@
+export interface EncryptResult {
+    ciphertext: Uint8Array;
+    iv: Uint8Array;
+    tag: Uint8Array;
+}
+export interface KeyEnvelope {
+    encrypted_key: Uint8Array;
+    iv: Uint8Array;
+    tag: Uint8Array;
+}
+/**
+ * Encrypt plaintext with AES-256-GCM.
+ * Returns separate ciphertext, IV, and authentication tag.
+ */
+export declare function encrypt(key: Uint8Array, plaintext: Uint8Array, aad?: Uint8Array): EncryptResult;
+/**
+ * Decrypt ciphertext with AES-256-GCM.
+ * Throws on authentication failure (wrong key, tampered data).
+ */
+export declare function decrypt(key: Uint8Array, ciphertext: Uint8Array, iv: Uint8Array, tag: Uint8Array, aad?: Uint8Array): Uint8Array;
+/**
+ * Wrap a key using AES-256-GCM (key wrapping via encryption).
+ */
+export declare function wrapKey(wrappingKey: Uint8Array, targetKey: Uint8Array, aad?: Uint8Array): KeyEnvelope;
+/**
+ * Unwrap a key using AES-256-GCM.
+ * Throws on authentication failure.
+ */
+export declare function unwrapKey(wrappingKey: Uint8Array, envelope: KeyEnvelope, aad?: Uint8Array): Uint8Array;

package/dist/src/crypto/aes-gcm.js

@@ -0,0 +1,44 @@
+import { gcm } from "@noble/ciphers/aes";
+import { randomBytes } from "@noble/hashes/utils";
+const IV_LENGTH = 12;
+const TAG_LENGTH = 16;
+/**
+ * Encrypt plaintext with AES-256-GCM.
+ * Returns separate ciphertext, IV, and authentication tag.
+ */
+export function encrypt(key, plaintext, aad) {
+    const iv = randomBytes(IV_LENGTH);
+    const cipher = gcm(key, iv, aad);
+    const sealed = cipher.encrypt(plaintext);
+    // @noble/ciphers appends the 16-byte tag to the ciphertext
+    return {
+        ciphertext: sealed.subarray(0, sealed.length - TAG_LENGTH),
+        iv,
+        tag: sealed.subarray(sealed.length - TAG_LENGTH),
+    };
+}
+/**
+ * Decrypt ciphertext with AES-256-GCM.
+ * Throws on authentication failure (wrong key, tampered data).
+ */
+export function decrypt(key, ciphertext, iv, tag, aad) {
+    const sealed = new Uint8Array(ciphertext.length + tag.length);
+    sealed.set(ciphertext);
+    sealed.set(tag, ciphertext.length);
+    const cipher = gcm(key, iv, aad);
+    return cipher.decrypt(sealed);
+}
+/**
+ * Wrap a key using AES-256-GCM (key wrapping via encryption).
+ */
+export function wrapKey(wrappingKey, targetKey, aad) {
+    const r = encrypt(wrappingKey, targetKey, aad);
+    return { encrypted_key: r.ciphertext, iv: r.iv, tag: r.tag };
+}
+/**
+ * Unwrap a key using AES-256-GCM.
+ * Throws on authentication failure.
+ */
+export function unwrapKey(wrappingKey, envelope, aad) {
+    return decrypt(wrappingKey, envelope.encrypted_key, envelope.iv, envelope.tag, aad);
+}

package/dist/src/crypto/device-keys.d.ts

@@ -0,0 +1,18 @@
+export interface DeviceKeyPair {
+    ed25519: {
+        publicKey: Uint8Array;
+        privateKey: Uint8Array;
+    };
+    x25519: {
+        publicKey: Uint8Array;
+        privateKey: Uint8Array;
+    };
+}
+/** Generate a fresh device key pair (Ed25519 for signing, X25519 for KEX). */
+export declare function generateDeviceKeyPair(): DeviceKeyPair;
+/** Sign a message with Ed25519. */
+export declare function sign(privateKey: Uint8Array, message: Uint8Array): Uint8Array;
+/** Verify an Ed25519 signature. */
+export declare function verify(publicKey: Uint8Array, message: Uint8Array, signature: Uint8Array): boolean;
+/** Compute X25519 shared secret for key exchange. */
+export declare function computeSharedSecret(privateKey: Uint8Array, publicKey: Uint8Array): Uint8Array;