local-first-auth-import-export 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Taddy Artist Database Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,244 @@
+# Local First Auth — Import / Export
+
+Let users **bring an identity they already have** into your mini app, or **back one up** — instead of creating a new profile.
+
+This is the companion to [`local-first-auth`](https://github.com/antler-browser/local-first-auth). That package *creates* a profile (mints a fresh Ed25519 keypair + `did:key`). This one *moves* one:
+
+- **Export** — download the user's profile (DID + public/private keypair, name, socials, avatar) as a portable `.json` file.
+- **Import** — restore that file on another device or in another app. **The DID is preserved** — no new keypair is generated.
+
+Both packages read and write the **same LocalStorage keys**, so they're fully interoperable: a profile created by `local-first-auth`'s `<Onboarding />` can be exported here, and a profile imported here works immediately with `local-first-auth`'s hooks, `window.localFirstAuth`, and JWT flow.
+
+## Installation
+
+```bash
+npm install local-first-auth-import-export
+```
+
+## Quick Start
+
+### React
+
+```tsx
+import { ImportExport } from 'local-first-auth-import-export/react'
+
+function BackupPage() {
+  return (
+    <ImportExport
+      onComplete={(profile) => console.log('Imported:', profile.did)}
+      customStyles={{ primaryColor: '#403B51' }}
+    />
+  )
+}
+```
+
+Or use the two halves independently:
+
+```tsx
+import { ImportProfile, ExportProfile } from 'local-first-auth-import-export/react'
+
+<ExportProfile onExport={(p) => console.log('Backed up', p.did)} />
+<ImportProfile onComplete={(p) => console.log('Restored', p.did)} />
+```
+
+### Vanilla JS
+
+```ts
+import {
+  exportProfile,
+  downloadProfile,
+  importProfile,
+  importProfileFromFile,
+} from 'local-first-auth-import-export'
+
+// Export — triggers a .json download
+downloadProfile()
+
+// Import — from a file input
+await importProfileFromFile(fileInput.files[0])
+
+// Import — from a JSON string, or even a bare private key
+const profile = await importProfile(jsonString)
+console.log(profile.did) // same DID as before
+```
+
+## ⚠️ Security
+
+**The exported file contains the user's private key in plain text.** Anyone who has it can act as that user — it *is* their identity.
+
+- Never upload it to a server, log it, or send it over the network.
+- Tell users to store it somewhere safe (a password manager, an encrypted drive).
+- `<ExportProfile />` shows this warning and keeps the key hidden behind a "Reveal" click by default.
+
+There is no password-encrypted export in v1.
+
+## The export file format
+
+The file is **self-identifying and versioned**, so any consumer can cheaply confirm it's a valid Local First Auth export before trusting it.
+
+```json
+{
+  "type": "local-first-auth:export",
+  "version": 1,
+  "did": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
+  "publicKey": "3dxk...",
+  "privateKey": "hR8f...",
+  "name": "Alice Anderson",
+  "socials": [{ "platform": "INSTAGRAM", "handle": "alice" }],
+  "avatar": null,
+  "exportedAt": "2026-07-12T10:30:00.000Z"
+}
+```
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `type` | string | Yes | Always `"local-first-auth:export"`. The magic string identifying the format. |
+| `version` | number | Yes | Schema version. Currently `1`. |
+| `did` | string | Yes | The user's DID (`did:key:z...`). |
+| `publicKey` | string | Yes | base64, 32-byte Ed25519 public key. |
+| `privateKey` | string | Yes | base64, 64-byte Ed25519 secret key. **Secret.** |
+| `name` | string | No | Display name. |
+| `socials` | array | No | `{ platform, handle }` entries. |
+| `avatar` | string \| null | No | Avatar as a `data:` URI. |
+| `exportedAt` | string | No | ISO 8601 export timestamp. |
+
+### Validation
+
+A file is valid only if **all** of these hold — `validateExportedProfile()` checks them in order:
+
+1. It parses as a JSON object.
+2. `type` is exactly `"local-first-auth:export"`.
+3. `version` is a supported version (`1`).
+4. `privateKey` is base64 that decodes to exactly **64 bytes**.
+5. **Consistency:** `did` and `publicKey` are re-derivable from `privateKey`. A file whose DID doesn't match its key is corrupt or tampered with, and is rejected.
+6. `socials`, if present, is an array of `{ platform, handle }`.
+
+```ts
+import { validateExportedProfile } from 'local-first-auth-import-export'
+
+const result = validateExportedProfile(untrustedJson)
+if (!result.valid) {
+  console.error(result.errors) // e.g. ["Unsupported export version: 99"]
+}
+```
+
+The private key is always the **source of truth**: on import, the DID and public key are re-derived from it rather than read from the file.
+
+## How import works
+
+An Ed25519 secret key is 64 bytes: a 32-byte seed followed by the 32-byte public key. So the private key alone is enough to rebuild the whole identity:
+
+```
+publicKey = secretKey[32..64]
+did       = "did:key:z" + base58btc(0xed 0x01 ‖ publicKey)
+```
+
+That's why importing **never mints a new keypair** — it recovers the existing one. This is the same `did:key` derivation `local-first-auth` uses, so the DIDs match exactly.
+
+Because of that, `importProfile()` also accepts a **bare base64 private key** with no envelope:
+
+```ts
+await importProfile('hR8f...') // name defaults to 'anonymous'
+```
+
+## Overwrite protection
+
+Importing over an existing, *different* identity would permanently destroy the user's current private key. So it throws unless you opt in:
+
+```ts
+await importProfile(json)                      // throws if a different profile exists
+await importProfile(json, { overwrite: true }) // explicitly replaces it
+```
+
+Re-importing the **same** DID is always allowed (it's idempotent). `<ImportProfile />` surfaces this as a warning plus a confirmation checkbox.
+
+## API Reference
+
+### Core
+
+```ts
+// Export
+exportProfile(): ExportedProfile | null
+exportProfileToJSON(pretty?: boolean): string | null
+downloadProfile(filename?: string): ExportedProfile | null
+defaultExportFilename(did: string): string
+
+// Import
+importProfile(input: string | ExportedProfile, opts?: { overwrite?: boolean }): Promise<Profile>
+importProfileFromFile(file: File, opts?: { overwrite?: boolean }): Promise<Profile>
+parseExportedProfile(input: string | ExportedProfile): ExportedProfile  // throws
+validateExportedProfile(input: unknown): ValidationResult               // never throws
+
+// Keys
+deriveKeysFromPrivateKey(privateKey: string): ProfileKeys
+validatePrivateKey(privateKey: unknown): { valid: boolean; error?: string }
+createDidFromPublicKey(publicKey: Uint8Array): string
+decodePublicKey(publicKey: string): Uint8Array
+
+// JWT (Local First Auth spec)
+createJWT(payload, privateKey): Promise<string>
+decodeJWT(jwt): { header, payload, signature }
+verifyJWT(jwt, publicKey: Uint8Array): boolean
+
+// Storage (same keys as local-first-auth)
+getCurrentProfile(), hasProfile(), clearProfile(), getPrivateKey(), STORAGE_KEYS
+
+// Window API
+injectLocalFirstAuthAPI(), removeLocalFirstAuthAPI(), hasLocalFirstAuthAPI()
+```
+
+### React
+
+```tsx
+<ImportProfile customStyles? onComplete?(profile) onBack? />
+<ExportProfile customStyles? onExport?(exported) emptyState? />
+<ImportExport  customStyles? onComplete? onExport? defaultTab? skipImport? skipExport? />
+
+const { profile, refresh } = useProfile()
+```
+
+All three components accept the same `customStyles` object as `local-first-auth`, so they theme identically:
+
+```tsx
+<ImportExport customStyles={{
+  primaryColor: '#403B51',
+  backgroundColor: '#ffffff',
+  borderRadius: '12px',
+  fontFamily: 'Inter, sans-serif',
+}} />
+```
+
+## Storage
+
+Identical to `local-first-auth` — this is what makes them interoperable:
+
+```js
+{
+  'local-first-auth:profile':    '{"did":"did:key:z6Mk...","name":"Alice",...}',
+  'local-first-auth:privateKey': 'base64-encoded-64-byte-key'
+}
+```
+
+After a successful import, `window.localFirstAuth` is injected, so `getProfileDetails()` immediately returns JWTs signed by the imported key.
+
+## Development
+
+```bash
+npm run build       # dual CJS+ESM build with type declarations
+npm run type-check  # tsc --noEmit
+npm test            # build, then round-trip + component render tests
+npm run dev:example # example app at http://localhost:5174
+```
+
+### Tests
+
+- `test/roundtrip.mjs` — verifies against the built `dist`: DID derivation matches `local-first-auth`'s algorithm exactly, export → clear → import preserves the DID, JWTs signed by the imported key verify, the validator rejects tampered files, and the overwrite guard holds.
+- `test/render.mjs` — smoke-renders the React components (including that the private key is hidden by default).
+
+### Example app
+
+`/example` is a Vite + React harness with four demos: **Round Trip** (runs the core assertions in-browser), **Export**, **Import**, and **Combined UI** (themed `<ImportExport />`). Run `npm run build` first — the example resolves the package through its built `dist`.
+
+## License
+
+MIT