@layers/amba 1.1.0 → 4.0.3

package/skill-bundle/references/identity.md

@@ -0,0 +1,395 @@
+# Identity
+
+End-user authentication for an Amba project: anonymous sessions, email/password, email OTP, SMS OTP, magic links, Sign in with Apple, Sign in with Google, and account linking. All flows return an `AuthResult` containing a `user` + a session token; the SDK persists tokens to the platform's native secure storage and replays them on the next launch. Subsequent SDK calls (collections, push, XP, etc.) are authenticated as the signed-in user automatically.
+
+There is no separate "identity provisioning" step — `auth` is the default surface for every project. Your job here is to (a) wire `Amba.configure(...)` plus the right sign-in calls into the user's entry file, and (b) where the user wants social sign-in, set the audience identifiers on the project so the server can verify identity tokens.
+
+## MCP tools
+
+| Tool | Purpose | Example args |
+| --- | --- | --- |
+| `amba_developer_me` | Verify the developer PAT and read the developer's profile. Pre-flight check before any provisioning. | `{}` |
+| `amba_projects_get` | Read a project's config (bundle id, OAuth client id, platform). | `{ project_id: "p_…" }` |
+| `amba_projects_update` | Set `bundle_id` (Apple audience) and `google_oauth_client_id` (Google audience). Required before Sign in with Apple / Google works. | `{ project_id, bundle_id: "com.example.fitness", google_oauth_client_id: "1234.apps.googleusercontent.com" }` |
+| `amba_users_list` | Browse end-users (app_users) of the project — useful as a smoke check after the first sign-in. | `{ project_id, limit: 20 }` |
+| `amba_users_get` | Fetch a single app_user by id. | `{ project_id, user_id }` |
+| `amba_users_bulk_update` | Set custom properties on many users at once (e.g. backfilling a `tier` property used for segmentation). | `{ project_id, user_ids: [...], properties: { tier: "trial" } }` |
+| `amba_create_api_key` / `amba_api_keys_create` | Mint additional client/server keys (e.g. a separate `production` key). | `{ project_id, key_type: "client", environment: "production" }` |
+| `amba_delete_api_key` / `amba_api_keys_delete` | Revoke a leaked key. | `{ project_id, api_key_id }` |
+| `amba_assign_role` / `amba_roles_assign` | Grant an RBAC role to an app_user (admin / moderator / etc.). | `{ project_id, user_id, role_id }` |
+
+There's no `amba_auth_*` namespace — auth is owned by the SDK on the client side, and there are no provisioning calls for it beyond setting the project's audience identifiers. If the user wants Apple/Google sign-in, the **mandatory** preflight is:
+
+```
+mcp__amba__amba_projects_update({
+  project_id: process.env.AMBA_PROJECT_ID,
+  bundle_id: "<their iOS bundle id>",                // for Apple
+  google_oauth_client_id: "<their Google OAuth client id>"  // for Google
+})
+```
+
+Without this, the server rejects identity tokens with `AUDIENCE_NOT_CONFIGURED` and the user thinks Amba is broken. If they don't know their bundle id, ask; if they don't have a Google OAuth client yet, tell them to create one at console.cloud.google.com and link it later.
+
+## SDK init per stack
+
+### Expo
+
+```bash
+npx expo install @layers/amba-expo @react-native-async-storage/async-storage
+```
+
+In `app.json` (`expo.plugins` array):
+
+```json
+{
+  "expo": {
+    "plugins": [
+      [
+        "@layers/amba-expo",
+        {
+          "apiKey": "<AMBA_CLIENT_KEY at build time>",
+          "scheme": "myapp",
+          "googleIosClientId": "<reverse-DNS form of your iOS Google client id>"
+        }
+      ]
+    ]
+  }
+}
+```
+
+In `app/_layout.tsx` (or whatever your root layout is):
+
+```tsx
+import { useEffect } from 'react';
+import { Amba } from '@layers/amba-expo';
+
+export default function RootLayout() {
+  useEffect(() => {
+    (async () => {
+      await Amba.configure({
+        apiKey: process.env.EXPO_PUBLIC_AMBA_CLIENT_KEY!,
+      });
+      // Anonymous-first. The SDK persists the session; on the next launch
+      // this call is a no-op (it returns the stored session).
+      await Amba.auth.signInAnonymously();
+    })();
+  }, []);
+  return /* … */ null;
+}
+```
+
+For Sign in with Apple, add `expo-apple-authentication`:
+
+```tsx
+import * as AppleAuthentication from 'expo-apple-authentication';
+import { Amba } from '@layers/amba-expo';
+
+async function signInWithApple() {
+  const credential = await AppleAuthentication.signInAsync({
+    requestedScopes: [
+      AppleAuthentication.AppleAuthenticationScope.FULL_NAME,
+      AppleAuthentication.AppleAuthenticationScope.EMAIL,
+    ],
+  });
+  if (credential.identityToken) {
+    await Amba.auth.signInWithApple(credential.identityToken);
+  }
+}
+```
+
+For Sign in with Google, add `expo-auth-session/providers/google`:
+
+```tsx
+import * as Google from 'expo-auth-session/providers/google';
+import { Amba } from '@layers/amba-expo';
+
+const [request, response, promptAsync] = Google.useIdTokenAuthRequest({
+  clientId: process.env.EXPO_PUBLIC_GOOGLE_CLIENT_ID!,
+});
+
+useEffect(() => {
+  if (response?.type === 'success' && response.params.id_token) {
+    Amba.auth.signInWithGoogle(response.params.id_token);
+  }
+}, [response]);
+```
+
+### React Native (bare)
+
+```bash
+npm install @layers/amba-react-native @react-native-async-storage/async-storage
+```
+
+In `App.tsx` (or `index.js`):
+
+```tsx
+import { useEffect } from 'react';
+import { Amba } from '@layers/amba-react-native';
+
+export default function App() {
+  useEffect(() => {
+    (async () => {
+      await Amba.configure({ apiKey: process.env.AMBA_CLIENT_KEY! });
+      await Amba.auth.signInAnonymously();
+    })();
+  }, []);
+  return /* … */ null;
+}
+```
+
+For email OTP (works in bare RN without any extra deps):
+
+```tsx
+await Amba.auth.requestEmailOtp(email);
+// user types in the 6-digit code from their inbox
+const result = await Amba.auth.verifyEmailOtp(email, code);
+// result.user is the signed-in app_user
+```
+
+For phone OTP:
+
+```tsx
+// phone must be E.164 (leading "+", 8-15 digits total)
+await Amba.auth.requestSmsOtp('+14155551234');
+await Amba.auth.verifySmsOtp('+14155551234', code);
+```
+
+### Web (browser / Next.js / Vite / Remix)
+
+```bash
+npm install @layers/amba-web
+# Optional React hooks layer:
+npm install @layers/amba-react
+```
+
+Bare web:
+
+```ts
+import { Amba } from '@layers/amba-web';
+
+await Amba.configure({
+  apiKey: import.meta.env.VITE_AMBA_CLIENT_KEY,
+});
+await Amba.auth.signInAnonymously();
+
+// Magic link
+await Amba.auth.requestMagicLink('user@example.com');
+// (user clicks email → arrives back with ?token=… in the URL)
+const params = new URLSearchParams(window.location.search);
+const token = params.get('token');
+if (token) {
+  await Amba.auth.verifyMagicLink(token);
+}
+```
+
+With React hooks (`@layers/amba-react`):
+
+```tsx
+import { Amba } from '@layers/amba-web';
+import { AmbaProvider, useUser } from '@layers/amba-react';
+
+await Amba.configure({ apiKey: import.meta.env.VITE_AMBA_CLIENT_KEY });
+
+function App() {
+  return (
+    <AmbaProvider>
+      <Inner />
+    </AmbaProvider>
+  );
+}
+
+function Inner() {
+  const { user, isAuthenticated, loading } = useUser();
+  if (loading) return <Spinner />;
+  if (!isAuthenticated) return <SignIn />;
+  return <Dashboard user={user!} />;
+}
+```
+
+Next.js — call `Amba.configure(...)` once at the top of `app/layout.tsx` (or `pages/_app.tsx`). Anonymous sign-in should happen on the client; do not call SDK functions in server components or `getServerSideProps`.
+
+### iOS (Swift, SPM)
+
+In `Package.swift` (or Xcode → File → Add Package Dependencies):
+
+```swift
+.package(url: "https://github.com/layers/amba-sdk-ios", from: "1.0.0")
+```
+
+In your `App` struct:
+
+```swift
+import SwiftUI
+import Amba
+
+@main
+struct MyApp: App {
+    init() {
+        Task {
+            try await Amba.configure(apiKey: ProcessInfo.processInfo.environment["AMBA_CLIENT_KEY"]!)
+            try await Amba.auth.signInAnonymously()
+        }
+    }
+    var body: some Scene {
+        WindowGroup { ContentView() }
+    }
+}
+```
+
+Sign in with Apple — use Apple's `AuthenticationServices` framework:
+
+```swift
+import AuthenticationServices
+import Amba
+
+func handleAppleSignIn(authorization: ASAuthorization) async throws {
+    guard let credential = authorization.credential as? ASAuthorizationAppleIDCredential,
+          let identityTokenData = credential.identityToken,
+          let identityToken = String(data: identityTokenData, encoding: .utf8) else { return }
+    try await Amba.auth.signInWithApple(identityToken: identityToken)
+}
+```
+
+For Sign in with Google in SwiftUI, use Google's `GoogleSignIn-iOS` SDK, capture the `idToken`, then:
+
+```swift
+try await Amba.auth.signInWithGoogle(idToken: idToken)
+```
+
+> Add the "Sign in with Apple" capability in **Xcode → target → Signing & Capabilities → +Capability**. Without it, the Apple auth call fails before it reaches Amba.
+
+### Android (Kotlin)
+
+In `app/build.gradle.kts`:
+
+```kotlin
+dependencies {
+    implementation("com.layers.amba:amba-sdk-android:0.1.0")
+}
+```
+
+In your `Application` subclass (create one if missing; register it in `AndroidManifest.xml` `<application android:name=".MyApp">`):
+
+```kotlin
+import android.app.Application
+import com.layers.amba.Amba
+import kotlinx.coroutines.GlobalScope
+import kotlinx.coroutines.launch
+
+class MyApp : Application() {
+    override fun onCreate() {
+        super.onCreate()
+        GlobalScope.launch {
+            Amba.configure(apiKey = BuildConfig.AMBA_CLIENT_KEY)
+            Amba.auth.signInAnonymously()
+        }
+    }
+}
+```
+
+Wire `AMBA_CLIENT_KEY` via `buildConfigField` in `app/build.gradle.kts`:
+
+```kotlin
+android {
+    defaultConfig {
+        buildConfigField("String", "AMBA_CLIENT_KEY", "\"${project.findProperty("AMBA_CLIENT_KEY") ?: ""}\"")
+    }
+}
+```
+
+Sign in with Google — use Google's `googleid` Credential Manager flow, capture the `idToken`, then:
+
+```kotlin
+Amba.auth.signInWithGoogle(idToken = idToken)
+```
+
+### Flutter
+
+In `pubspec.yaml`:
+
+```yaml
+dependencies:
+  amba: ^1.0.0
+```
+
+`flutter pub add amba`.
+
+In `lib/main.dart`:
+
+```dart
+import 'package:amba/amba.dart';
+import 'package:flutter/material.dart';
+
+Future<void> main() async {
+  WidgetsFlutterBinding.ensureInitialized();
+  await Amba.configure(apiKey: const String.fromEnvironment('AMBA_CLIENT_KEY'));
+  await Amba.auth.signInAnonymously();
+  runApp(const MyApp());
+}
+```
+
+Pass the key in: `flutter run --dart-define=AMBA_CLIENT_KEY=$AMBA_CLIENT_KEY`. For Sign in with Apple, add the `sign_in_with_apple` pub package, capture the identity token, then:
+
+```dart
+await Amba.auth.signInWithApple(identityToken: credential.identityToken!);
+```
+
+For Sign in with Google, use `google_sign_in`, capture `googleAuth.idToken`, then:
+
+```dart
+await Amba.auth.signInWithGoogle(idToken: googleAuth.idToken!);
+```
+
+## Common follow-ups
+
+Ask one bundled multi-choice — don't ask one at a time.
+
+1. **Which sign-in methods do you want?** (multi-select)
+   - [x] Anonymous (recommended — call at app start, lets users use the app immediately)
+   - [ ] Email + password
+   - [ ] Email OTP (6-digit code emailed)
+   - [ ] Magic link (single click email)
+   - [ ] Phone OTP / SMS (E.164, requires SMS provider configured)
+   - [ ] Sign in with Apple (iOS / web; required for iOS apps that have any third-party auth per App Store guideline 4.8)
+   - [ ] Sign in with Google (Android / iOS / web)
+
+2. **If Apple is selected:** what's your iOS bundle id? (`com.example.fitness`) — required for `bundle_id` on `amba_projects_update`.
+
+3. **If Google is selected:** what's your Google OAuth client id? Format: `123456789-abc.apps.googleusercontent.com`. If they don't have one yet, point them at console.cloud.google.com and proceed without it — they can paste it later with `amba_projects_update`.
+
+4. **If anonymous is selected:** when do you want users to upgrade?
+   - On a "Save your progress" prompt (offer Apple/Google linking)
+   - Behind a paywall / premium gate
+   - Never auto-prompt (user upgrades from settings)
+   - Defaults to "never auto-prompt".
+
+## Re-run behavior
+
+On a second `/amba` invocation that targets identity:
+
+1. Read `.amba/wired.json` — if `identity` is already listed, skip the SDK install + `Amba.configure(...)` step and only add new sign-in methods.
+
+2. Call `amba_projects_get({ project_id })` to read current `bundle_id` and `google_oauth_client_id`. Compare to what the user gave you:
+   - If both already set → no `amba_projects_update` needed.
+   - If user is adding a new social provider that needs an audience → call `amba_projects_update` with just the new field. Don't blow away the existing one.
+
+3. For new sign-in methods, append the per-method code block to the existing entry file *without* re-emitting `Amba.configure(...)` (it's already there). Detection: search for `Amba.configure` in the entry file; if present, skip the configure block.
+
+4. Update `.amba/wired.json`:
+
+   ```json
+   {
+     "surfaces": {
+       "identity": {
+         "wired_at": "<original timestamp>",
+         "extended_at": "<now>",
+         "methods": ["anonymous", "apple", "google", "email_otp"]
+       }
+     }
+   }
+   ```
+
+5. If the user asks to "switch from anonymous to email-only" or similar destructive change, **don't auto-do it**. Explain that existing anonymous user data would be unreachable without a link flow, then offer:
+   - Add the new method alongside anonymous (recommended)
+   - Add a forced upgrade prompt in onboarding
+   - Migrate manually via `Amba.auth.linkEmailOtp(email, code)` — keeps existing user data