zulip · gnprice · Jun 30, 2020 · Apr 10, 2020 · Jun 30, 2020 · Jun 30, 2020
diff --git a/docs/howto/dev-server.md b/docs/howto/dev-server.md
@@ -202,7 +202,7 @@ This will be `http://ADDRESS:9991`, where `ADDRESS` is the address you
 identified in step 2.  (Be sure to type the `http://`.)
 
 This should get you the login screen!  Unless you're working on the login
-flow itself, tap "Log in with dev account"; then pick any user to log in as.
+flow itself, tap "Sign in with dev account"; then pick any user to log in as.
 
 If you need to work more closely with authentication systems, or if you need
 to use the [Zulip REST API][rest-api], which requires an API key, this

diff --git a/docs/howto/ios-tips.md b/docs/howto/ios-tips.md
@@ -84,3 +84,87 @@ It seems like there's some caching strategy to avoid fetching
 `.podspec` files unnecessarily, potentially with network requests.
 (See
 [discussion](https://chat.zulip.org/#narrow/stream/243-mobile-team/topic/.23M3548.20RN.20v0.2E60.2E0.20upgrade/near/896746).)
+
+## Sign in with Apple
+
+To set up your [development server](./dev-server.md) to use Apple
+authentication ("Sign in with Apple"), you'll want to follow almost
+[these
+steps](https://zulip.readthedocs.io/en/latest/production/authentication-methods.html#sign-in-with-apple),
+but with a few things to keep in mind:
+
+- If you don't have your own Apple Developer account (there's an
+  annual fee), please ask Greg to set up test credentials and send
+  them to you.
+  These will be associated with the Kandra team, so
+  [please](https://chat.zulip.org/#narrow/stream/3-backend/topic/apple.20auth/near/915391)
+  let him know when you're finished with the credentials so he can
+  revoke them. Please don't abuse them with deliberate spam, as
+  that goes on our reputation.
+- Use the domain `zulipdev.com` where Apple asks for a domain;
+  [`localhost` won't
+  work](https://chat.zulip.org/#narrow/stream/3-backend/topic/Apple.20Auth/near/831533).
+  On the public Internet, `zulipdev.com` resolves to `127.0.0.1`.
+  - `127.0.0.1` (also what `localhost` points to) points to the
+    machine you're on. When you're on a physical device, that's the
+    device itself, not the device (your computer) that's running the
+    dev server. So you won't be able to connect using `zulipdev.com`
+    on a physical device.
+  - Empirically, there's no problem using the iOS simulator on the
+    computer running the dev server; it seems the iOS simulator shares
+    its network interface with the computer it's running on. To use
+    the native flow, you will be able to sign into the simulator at
+    the "device" level just as you would on a real device.
+  - Temporarily allow the app to access `http://zulipdev.com` as
+    described in the section on `NSAppTransportSecurity` exceptions,
+    below.
+
+To test the native flow, which uses an Apple ID you've authenticated
+with in System Preferences, go to the ZulipMobile target in the
+project and targets list, and, under General > Identity, set the
+Bundle Identifier field to your development App ID (a.k.a. Bundle ID).
+If you've already installed a build that used the canonical Bundle
+Identifier, you'll see two app icons on your home screen. Be sure to
+open the correct one; it might be easiest to delete them both and
+reinstall to prevent any doubt.
+
+You should now be able to enter `http://zulipdev.com:9991` (not
+`https://`), see the "Sign in with Apple" button, and use it
+successfully.
+
+## Adding `http://` exceptions to `NSAppTransportSecurity` in `Info.plist`
+
+If you need to connect to `http://zulipdev.com` or another host with
+the insecure `http://`, you'll need to tell the app to make an
+exception under iOS's "App Transport Security", either to allow access
+any host with `http://`, or just to specific domains.
+
+These exceptions should never be committed to master, as there aren't
+any insecure domains we want to connect to in production.
+
+To add an exception for the `zulipdev.com` domain, add the following
+in `ios/ZulipMobile/Info.plist`:
+
+```diff
+   <key>NSAppTransportSecurity</key>
+   <dict>
+     <key>NSExceptionDomains</key>
+     <dict>
+       <key>localhost</key>
+       <dict>
+         <key>NSTemporaryExceptionAllowsInsecureHTTPLoads</key>
+         <true/>
+       </dict>
++      <key>zulipdev.com</key>
++      <dict>
++        <key>NSTemporaryExceptionAllowsInsecureHTTPLoads</key>
++        <true/>
++      </dict>
+     </dict>
+   </dict>
+```
+
+See
+[discussion](https://chat.zulip.org/#narrow/stream/243-mobile-team/topic/Apple.20ATS.20for.20debug/near/883318)
+for more convenient solutions if we find we have to allow this
+regularly.
diff --git a/docs/howto/libdefs.md b/docs/howto/libdefs.md
@@ -152,3 +152,43 @@ Flow and FlowTyped about not being able to import third-party types
 into one's own libdefs that haven't been resolved. [9]
 
 [9]: https://github.com/zulip/zulip-mobile/issues/3458#issuecomment-639859987
+
+## Expo packages (made available through Unimodules)
+
+We're starting to see a pattern developing with these, e.g.:
+
+- `expo-apple-authentication`
+- `expo-screen-orientation`
+
+Namely:
+
+1. See what `node_modules/expo-name-of-package/build/index.d.ts`
+   depends on; it's probably at least `'./NameOfPackage'` and
+   `'./NameOfPackage.types'`.
+
+   Assuming so, make a `declare module expo-name-of-package` block and
+   have it do what that `index.d.ts` does, maybe
+
+   ```javascript
+   declare module 'expo-name-of-package' {
+     declare export * from 'expo-name-of-package/build/NameOfPackage'
+     declare export * from 'expo-name-of-package/build/NameOfPackage.types'
+   }
+   ```
+
+2. Run `node_modules/expo-name-of-package/build/NameOfPackage.d.ts`
+   through Flowgen and paste the output into a
+   `declare module 'expo-name-of-package/build/NameOfPackage'`
+   block.
+2. Run `node_modules/expo-name-of-package/build/PackageName.types'`
+   through Flowgen and paste the output into a
+   `declare module 'expo-screen-orientation/build/ScreenOrientation.types'`
+   block.
+3. Make any necessary syntactic fixes based on error messages (in
+   particular, replacing `export` with `declare export` everywhere may
+   be necessary) or adjustments to imports. You may only import from
+   something that's been declared in that same file, with
+   `declare export` [1] [2].
+
+[1]: https://github.com/flow-typed/flow-typed/blob/master/CONTRIBUTING.md#dont-import-types-from-other-libdefs
+[2]: See discussion around https://chat.zulip.org/#narrow/stream/243-mobile-team/topic/libdef.3A.20react-native-webview/near/896713.