local-first-auth-import-export 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,396 @@
+/**
+ * Local First Auth Import/Export Types
+ * Compatible with the Local First Auth Specification
+ */
+interface SocialLink {
+    platform: SocialPlatform;
+    handle: string;
+}
+type SocialPlatform = 'INSTAGRAM' | 'X' | 'BLUESKY' | 'LINKEDIN' | 'YOUTUBE' | 'SPOTIFY' | 'TIKTOK' | 'SNAPCHAT' | 'GITHUB' | 'FACEBOOK' | 'REDDIT' | 'DISCORD' | 'TWITCH' | 'TELEGRAM' | 'PINTEREST' | 'TUMBLR' | 'SOUNDCLOUD' | 'BANDCAMP' | 'PATREON' | 'KO_FI' | 'MASTODON' | 'WEBSITE' | 'EMAIL';
+interface Profile {
+    did: string;
+    name: string;
+    socials?: SocialLink[];
+    avatar?: string | null;
+}
+interface ProfileKeys {
+    did: string;
+    privateKey: string;
+    publicKey: string;
+}
+interface StoredProfile {
+    did: string;
+    name: string;
+    socials?: SocialLink[];
+    avatar?: string | null;
+}
+/**
+ * The magic string identifying a Local First Auth export file.
+ * Present as the `type` field so a consumer can cheaply confirm the format.
+ */
+declare const EXPORT_FILE_TYPE: "local-first-auth:export";
+/**
+ * The current export file schema version.
+ */
+declare const EXPORT_FILE_VERSION: 1;
+/**
+ * A Local First Auth profile export.
+ *
+ * This is the exact shape of the exported `.json` file. It is self-identifying
+ * (`type` + `version`) and internally consistent: `did` and `publicKey` MUST be
+ * re-derivable from `privateKey`, which lets any consumer validate the file
+ * without trusting its contents.
+ *
+ * SECURITY: this contains a plaintext private key. Anyone who has it can act as
+ * the user. Never transmit or log it.
+ */
+interface ExportedProfile {
+    /** Fixed magic string identifying this as a Local First Auth export */
+    type: typeof EXPORT_FILE_TYPE;
+    /** Schema version, for forward compatibility */
+    version: typeof EXPORT_FILE_VERSION;
+    /** The user's DID (did:key:z...) */
+    did: string;
+    /** base64-encoded 32-byte Ed25519 public key */
+    publicKey: string;
+    /** base64-encoded 64-byte Ed25519 secret key */
+    privateKey: string;
+    /** Display name */
+    name?: string;
+    /** Social links */
+    socials?: SocialLink[];
+    /** Avatar as a data: URI */
+    avatar?: string | null;
+    /** ISO 8601 timestamp of when the file was exported */
+    exportedAt?: string;
+}
+/**
+ * Result of validating an untrusted value against the export file format.
+ */
+interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+    profile?: ExportedProfile;
+}
+/**
+ * Options for importing a profile.
+ */
+interface ImportOptions {
+    /**
+     * Replace an existing profile with a different DID.
+     * Defaults to false — importing over a different identity throws unless this
+     * is explicitly set, to guard against accidentally destroying the user's keys.
+     */
+    overwrite?: boolean;
+}
+interface LocalFirstAuth {
+    getProfileDetails(): Promise<string>;
+    getAvatar(): Promise<string | null>;
+    getAppDetails(): AppDetails;
+    requestPermission(permission: string): Promise<boolean>;
+    close(): void;
+}
+interface AppDetails {
+    name: string;
+    version: string;
+    platform: 'ios' | 'android' | 'browser';
+    supportedPermissions: string[];
+}
+interface JWTHeader {
+    alg: 'EdDSA';
+    typ: 'JWT';
+}
+interface JWTPayload {
+    iss: string;
+    aud: string;
+    iat: number;
+    exp: number;
+    type: string;
+    data?: any;
+}
+interface CustomStyles {
+    primaryColor?: string;
+    backgroundColor?: string;
+    textColor?: string;
+    borderRadius?: string;
+    fontFamily?: string;
+    buttonRadius?: string;
+    inputRadius?: string;
+    inputTextColor?: string;
+    inputBackgroundColor?: string;
+    /** Scale factor for button press animation on mobile (0-1). Default: 0.95 */
+    mobileButtonPressScale?: number;
+    /** Color for mobile tap highlight. Default: 'transparent' */
+    mobileTapHighlightColor?: string;
+    /** Enable safe area insets for iOS notch / Android nav bars. Default: true */
+    useSafeAreaInsets?: boolean;
+}
+interface ExportProfileProps {
+    customStyles?: CustomStyles;
+    /** Called after the user downloads their profile backup */
+    onExport?: (profile: ExportedProfile) => void;
+    /** Rendered when no profile exists. Defaults to a short message. */
+    emptyState?: React.ReactNode;
+}
+interface ImportProfileProps {
+    customStyles?: CustomStyles;
+    /** Called with the imported profile on success */
+    onComplete?: (profile: Profile) => void;
+    onBack?: () => void;
+}
+interface ImportExportProps {
+    customStyles?: CustomStyles;
+    onComplete?: (profile: Profile) => void;
+    onExport?: (profile: ExportedProfile) => void;
+    /** Which tab is shown first. Default: 'import' */
+    defaultTab?: 'import' | 'export';
+    /** Hide the import tab */
+    skipImport?: boolean;
+    /** Hide the export tab */
+    skipExport?: boolean;
+}
+
+/**
+ * Cryptographic utilities for DID derivation and JWT signing.
+ *
+ * Mirrors local-first-auth's crypto layer so that keys/DIDs/JWTs produced here
+ * are byte-for-byte compatible, and adds the primitives needed to reconstruct an
+ * identity from an existing private key (rather than generating a new one).
+ */
+
+/** Ed25519 secret key size in bytes (32-byte seed + 32-byte public key) */
+declare const SECRET_KEY_SIZE = 64;
+/** Ed25519 public key size in bytes */
+declare const PUBLIC_KEY_SIZE = 32;
+/**
+ * Helper to encode/decode base64url (RFC 4648)
+ */
+declare const base64url: {
+    encode: (input: Uint8Array) => string;
+    decode: (input: string) => Uint8Array;
+};
+/**
+ * Create a did:key DID from an Ed25519 public key
+ *
+ * @param publicKey - The Ed25519 public key as Uint8Array (32 bytes)
+ * @returns The did:key formatted DID string
+ */
+declare function createDidFromPublicKey(publicKey: Uint8Array): string;
+/**
+ * Validate that a string is a usable Ed25519 private key.
+ *
+ * A valid key is base64 that decodes to exactly 64 bytes (the Ed25519 secret
+ * key: a 32-byte seed followed by the 32-byte public key).
+ */
+declare function validatePrivateKey(privateKey: unknown): {
+    valid: boolean;
+    error?: string;
+};
+/**
+ * Reconstruct a full identity (DID + public key) from an existing private key.
+ *
+ * This is the core of "import": an Ed25519 secret key already contains its
+ * public key in the final 32 bytes, so the private key alone is enough to
+ * recover the complete identity. No new keypair is generated.
+ *
+ * @param privateKey - base64-encoded 64-byte Ed25519 secret key
+ * @returns The derived { did, publicKey, privateKey }
+ * @throws If the private key is malformed
+ */
+declare function deriveKeysFromPrivateKey(privateKey: string): ProfileKeys;
+/**
+ * Decode a base64-encoded public key back into bytes (useful for verifyJWT)
+ */
+declare function decodePublicKey(publicKey: string): Uint8Array;
+/**
+ * Create and sign a JWT using Ed25519
+ *
+ * @param payload - JWT payload containing claims
+ * @param privateKey - base64-encoded 64-byte Ed25519 secret key
+ * @returns Signed JWT string
+ */
+declare function createJWT(payload: JWTPayload, privateKey: string): Promise<string>;
+/**
+ * Decode a JWT (for debugging - does NOT verify the signature)
+ */
+declare function decodeJWT(jwt: string): {
+    header: JWTHeader;
+    payload: JWTPayload;
+    signature: string;
+};
+/**
+ * Verify a JWT signature against an Ed25519 public key
+ *
+ * @param jwt - The JWT string to verify
+ * @param publicKey - The Ed25519 public key (32 bytes)
+ */
+declare function verifyJWT(jwt: string, publicKey: Uint8Array): boolean;
+
+/**
+ * LocalStorage wrapper for profile storage.
+ *
+ * IMPORTANT: these storage keys are intentionally identical to the ones used by
+ * the `local-first-auth` package. That is what makes the two interoperable — a
+ * profile created by local-first-auth's <Onboarding> can be exported here, and a
+ * profile imported here is immediately usable by local-first-auth's hooks and
+ * window API. Do not namespace these differently.
+ */
+
+declare const STORAGE_KEYS: {
+    readonly PROFILE: "local-first-auth:profile";
+    readonly PRIVATE_KEY: "local-first-auth:privateKey";
+};
+/**
+ * Save profile to LocalStorage
+ */
+declare function saveProfile(profile: StoredProfile): void;
+/**
+ * Get profile from LocalStorage
+ */
+declare function getProfile(): StoredProfile | null;
+/**
+ * Save private key to LocalStorage
+ */
+declare function savePrivateKey(privateKey: string): void;
+/**
+ * Get private key from LocalStorage
+ */
+declare function getPrivateKey(): string | null;
+/**
+ * Clear all stored profile data
+ */
+declare function clearProfile(): void;
+/**
+ * Check if a profile exists in storage
+ */
+declare function hasProfile(): boolean;
+/**
+ * Get the current profile (requires both the profile and its private key)
+ */
+declare function getCurrentProfile(): Profile | null;
+
+/**
+ * Export the current profile (including its keypair) as a portable JSON file.
+ *
+ * SECURITY: the exported file contains a plaintext private key. Anyone who has
+ * it can act as the user. Surface a clear warning in your UI, and never send the
+ * file to a server or log it.
+ */
+
+/**
+ * Build the exportable representation of the current profile.
+ *
+ * The DID and public key are re-derived from the stored private key rather than
+ * read from storage, so the resulting file is always internally consistent.
+ *
+ * @returns The ExportedProfile, or null if there is no profile to export.
+ */
+declare function exportProfile(): ExportedProfile | null;
+/**
+ * Serialize the current profile to a JSON string.
+ *
+ * @param pretty - Pretty-print the JSON (default true)
+ * @returns The JSON string, or null if there is no profile to export.
+ */
+declare function exportProfileToJSON(pretty?: boolean): string | null;
+/**
+ * Build a default filename for a profile backup, e.g.
+ * `local-first-auth-profile-z6MkhaXg.json`
+ */
+declare function defaultExportFilename(did: string): string;
+/**
+ * Download the current profile as a .json file in the browser.
+ *
+ * @param filename - Optional filename. Defaults to `local-first-auth-profile-<key>.json`
+ * @returns The exported profile, or null if there was nothing to export.
+ */
+declare function downloadProfile(filename?: string): ExportedProfile | null;
+
+/**
+ * Import an existing profile (public + private keypair) from an export file.
+ *
+ * Importing adopts an identity the user already has — no new keypair is minted.
+ * The private key is the source of truth: the DID and public key are always
+ * re-derived from it, never trusted from the file.
+ */
+
+/**
+ * Validate an untrusted value against the Local First Auth export file format.
+ *
+ * Checks, in order:
+ *  1. It parses as an object (a string is JSON.parse'd first)
+ *  2. `type` is the `local-first-auth:export` magic string
+ *  3. `version` is a supported schema version
+ *  4. `privateKey` is base64 that decodes to exactly 64 bytes
+ *  5. `did` / `publicKey` are re-derivable from `privateKey` (consistency check)
+ *  6. `socials`, if present, is a well-formed array
+ *
+ * This never throws — inspect `valid` and `errors`.
+ */
+declare function validateExportedProfile(input: unknown): ValidationResult;
+/**
+ * Normalize any supported import input into a valid ExportedProfile.
+ *
+ * Accepts:
+ *  - an `ExportedProfile` object
+ *  - a JSON string of an export file
+ *  - a bare base64 private key (convenience — the envelope is synthesized)
+ *
+ * @throws Error with a human-readable message if the input is unusable.
+ */
+declare function parseExportedProfile(input: string | ExportedProfile): ExportedProfile;
+/**
+ * Import a profile, adopting its existing identity.
+ *
+ * Saves the profile and private key to storage (the same keys local-first-auth
+ * uses) and injects `window.localFirstAuth`, so the app is immediately
+ * authenticated as the imported user.
+ *
+ * If a profile with a *different* DID already exists, this throws unless
+ * `overwrite: true` is passed — importing would otherwise silently destroy the
+ * user's existing keys.
+ *
+ * @param input - An export file (object or JSON string), or a bare private key
+ * @param options - `{ overwrite }` to replace an existing, different identity
+ */
+declare function importProfile(input: string | ExportedProfile, options?: ImportOptions): Promise<Profile>;
+/**
+ * Import a profile from a File (e.g. from an <input type="file"> or a drop).
+ */
+declare function importProfileFromFile(file: File, options?: ImportOptions): Promise<Profile>;
+
+/**
+ * Local First Auth API implementation.
+ *
+ * Implements the LocalFirstAuth interface from the Local First Auth Specification
+ * and injects it at window.localFirstAuth. Mirrors local-first-auth's api.ts so an
+ * imported profile behaves exactly like one created through onboarding.
+ */
+
+declare class LocalFirstAuthAPI implements LocalFirstAuth {
+    /**
+     * Get profile details as a signed JWT
+     */
+    getProfileDetails(): Promise<string>;
+    /**
+     * Get avatar as base64-encoded string in a signed JWT
+     */
+    getAvatar(): Promise<string | null>;
+    getAppDetails(): AppDetails;
+    requestPermission(permission: string): Promise<boolean>;
+    close(): void;
+}
+/**
+ * Inject the Local First Auth API into the window object
+ */
+declare function injectLocalFirstAuthAPI(): void;
+/**
+ * Remove the Local First Auth API from the window object
+ */
+declare function removeLocalFirstAuthAPI(): void;
+/**
+ * Check if the Local First Auth API is available
+ */
+declare function hasLocalFirstAuthAPI(): boolean;
+
+export { type AppDetails, type CustomStyles, EXPORT_FILE_TYPE, EXPORT_FILE_VERSION, type ExportProfileProps, type ExportedProfile, type ImportExportProps, type ImportOptions, type ImportProfileProps, type JWTHeader, type JWTPayload, type LocalFirstAuth, LocalFirstAuthAPI, PUBLIC_KEY_SIZE, type Profile, type ProfileKeys, SECRET_KEY_SIZE, STORAGE_KEYS, type SocialLink, type SocialPlatform, type StoredProfile, type ValidationResult, base64url, clearProfile, createDidFromPublicKey, createJWT, decodeJWT, decodePublicKey, defaultExportFilename, deriveKeysFromPrivateKey, downloadProfile, exportProfile, exportProfileToJSON, getCurrentProfile, getPrivateKey, getProfile, hasLocalFirstAuthAPI, hasProfile, importProfile, importProfileFromFile, injectLocalFirstAuthAPI, parseExportedProfile, removeLocalFirstAuthAPI, savePrivateKey, saveProfile, validateExportedProfile, validatePrivateKey, verifyJWT };