Invite people

By the end of this page Alice can invite Bob into Book club, and Bob joins with two codes: one she sends him and one she tells him.

Background

An invitation takes two codes, which travel by different routes. The invitation code is long and goes in a message or a link. The authorization code is six digits, which the host sees once the guest connects and passes on another way, such as reading it aloud. Someone who intercepts only the message cannot get in.

When the guest enters the right code, the two sides exchange contact cards: each names its identity and carries the keys the other needs. Then the host writes a delegation, a statement signed by a member allowed to make it, that admits the guest. Every member checks that delegation for itself, so no server has to vouch for the guest.

An invitation is a Flow. Its events say where the handshake is: connecting, connected, readyForAuthentication, authenticating, then success, cancelled or error. Invitations covers the rest.

Steps

1. Invite someone. Space.share starts the invitation on the host, and Invitation.code is the code to send. shared-secret makes the guest enter the authorization code. Invite calls this and shows the code.

   src/app/Invitations.tsx

   import * as Effect from 'effect/Effect';
   import React, { useEffect, useRef, useState } from 'react';
   
   import { Invitation, Space } from '@dxos/halo';
   import { useHaloServices, useInvitationFlow } from '@dxos/halo-react';
   import { type SpaceId } from '@dxos/keys';
   
   import { Copyable, Prompt } from './ui.tsx';
   
   /** Invite someone to the current space, or join a space with a code. */
   export const InviteBar = ({ spaceId }: { spaceId?: SpaceId }) => {
     const services = useHaloServices();
     const [open, setOpen] = useState<'invite' | 'join'>();
   
     /** Starts an invitation to the space, and returns the flow and the code to send. */
     const handleInvite = (spaceId: SpaceId) =>
       Effect.gen(function* () {
         const flow = yield* Space.share(spaceId, {
           authMethod: 'shared-secret',
         });
         const code = yield* Invitation.code(flow);
         return { flow, code };
       }).pipe(Effect.provide(services), Effect.runPromise);
   
   

2. Join. On the guest, Space.join redeems the code and returns the guest’s own flow. Join calls this.

   src/app/Invitations.tsx

   import * as Effect from 'effect/Effect';
   import React, { useEffect, useRef, useState } from 'react';
   
   import { Invitation, Space } from '@dxos/halo';
   import { useHaloServices, useInvitationFlow } from '@dxos/halo-react';
   import { type SpaceId } from '@dxos/keys';
   
   import { Copyable, Prompt } from './ui.tsx';
   
   /** Invite someone to the current space, or join a space with a code. */
   export const InviteBar = ({ spaceId }: { spaceId?: SpaceId }) => {
     const services = useHaloServices();
     const [open, setOpen] = useState<'invite' | 'join'>();
   
     /** Starts an invitation to the space, and returns the flow and the code to send. */
     const handleInvite = (spaceId: SpaceId) =>
       Effect.gen(function* () {
         const flow = yield* Space.share(spaceId, {
           authMethod: 'shared-secret',
         });
         const code = yield* Invitation.code(flow);
         return { flow, code };
       }).pipe(Effect.provide(services), Effect.runPromise);
   
     /** Redeems the invitation `code`, and returns the flow. */
     const handleJoin = (code: string) =>
       Space.join(code).pipe(Effect.provide(services), Effect.runPromise);
   
   

3. Follow the handshake. useInvitationFlow returns the flow’s latest event and re-renders on each one, until the flow ends. Both sides follow their flow with it. On the host, readyForAuthentication carries the authorization code to show; on the guest, it is the moment to ask for it.

   src/app/Invitations.tsx

   import { useHaloServices, useInvitationFlow } from '@dxos/halo-react';
   import { type SpaceId } from '@dxos/keys';
   
   import { Copyable, Prompt } from './ui.tsx';
   
   /** Invite someone to the current space, or join a space with a code. */
   export const InviteBar = ({ spaceId }: { spaceId?: SpaceId }) => {
     const services = useHaloServices();
     const [open, setOpen] = useState<'invite' | 'join'>();
   
     /** Starts an invitation to the space, and returns the flow and the code to send. */
     const handleInvite = (spaceId: SpaceId) =>
       Effect.gen(function* () {
         const flow = yield* Space.share(spaceId, {
           authMethod: 'shared-secret',
         });
         const code = yield* Invitation.code(flow);
         return { flow, code };
       }).pipe(Effect.provide(services), Effect.runPromise);
   
     /** Redeems the invitation `code`, and returns the flow. */
     const handleJoin = (code: string) =>
       Space.join(code).pipe(Effect.provide(services), Effect.runPromise);
   
     return (
       <div className='cb-invite'>
         <div className='cb-row'>
           <button
             className='cb-button'
             disabled={!spaceId}
             aria-pressed={open === 'invite'}
             onClick={() => setOpen(open === 'invite' ? undefined : 'invite')}
           >
             Invite
           </button>
           <button
             className='cb-button'
             aria-pressed={open === 'join'}
             onClick={() => setOpen(open === 'join' ? undefined : 'join')}
           >
             Join
           </button>
         </div>
         {open === 'invite' && spaceId && (
           <Host
             key={spaceId}
             start={() => handleInvite(spaceId)}
             send='Send this invitation code to the person you invite:'
           />
         )}
         {open === 'join' && (
           <Guest
             label='Invitation code'
             join={handleJoin}
             onDone={() => setOpen(undefined)}
           />
         )}
       </div>
     );
   };
   
   type Flow = { flow: Invitation.Flow; code: string };
   
   /** The host's side of an invitation: the code to send, then the authorization code to tell. */
   export const Host = ({
     start,
     send,
   }: {
     start: () => Promise<Flow>;
     send: string;
   }) => {
     const [flow, setFlow] = useState<Flow>();
     const [error, setError] = useState<string>();
     const started = useRef(false);
     useEffect(() => {
       if (!started.current) {
         started.current = true;
         start().then(setFlow, (error) => setError(String(error)));
       }
     }, []);
     /** The flow's latest event, re-rendering as the handshake moves on. */
     const { event } = useInvitationFlow(flow?.flow);
   
   

4. Send the authorization code. On the guest, Invitation.authenticate sends the code the host showed. Send calls this.

   src/app/Invitations.tsx

   import * as Effect from 'effect/Effect';
   import React, { useEffect, useRef, useState } from 'react';
   
   import { Invitation, Space } from '@dxos/halo';
   import { useHaloServices, useInvitationFlow } from '@dxos/halo-react';
   import { type SpaceId } from '@dxos/keys';
   
   import { Copyable, Prompt } from './ui.tsx';
   
   /** Invite someone to the current space, or join a space with a code. */
   export const InviteBar = ({ spaceId }: { spaceId?: SpaceId }) => {
     const services = useHaloServices();
     const [open, setOpen] = useState<'invite' | 'join'>();
   
     /** Starts an invitation to the space, and returns the flow and the code to send. */
     const handleInvite = (spaceId: SpaceId) =>
       Effect.gen(function* () {
         const flow = yield* Space.share(spaceId, {
           authMethod: 'shared-secret',
         });
         const code = yield* Invitation.code(flow);
         return { flow, code };
       }).pipe(Effect.provide(services), Effect.runPromise);
   
     /** Redeems the invitation `code`, and returns the flow. */
     const handleJoin = (code: string) =>
       Space.join(code).pipe(Effect.provide(services), Effect.runPromise);
   
     return (
       <div className='cb-invite'>
         <div className='cb-row'>
           <button
             className='cb-button'
             disabled={!spaceId}
             aria-pressed={open === 'invite'}
             onClick={() => setOpen(open === 'invite' ? undefined : 'invite')}
           >
             Invite
           </button>
           <button
             className='cb-button'
             aria-pressed={open === 'join'}
             onClick={() => setOpen(open === 'join' ? undefined : 'join')}
           >
             Join
           </button>
         </div>
         {open === 'invite' && spaceId && (
           <Host
             key={spaceId}
             start={() => handleInvite(spaceId)}
             send='Send this invitation code to the person you invite:'
           />
         )}
         {open === 'join' && (
           <Guest
             label='Invitation code'
             join={handleJoin}
             onDone={() => setOpen(undefined)}
           />
         )}
       </div>
     );
   };
   
   type Flow = { flow: Invitation.Flow; code: string };
   
   /** The host's side of an invitation: the code to send, then the authorization code to tell. */
   export const Host = ({
     start,
     send,
   }: {
     start: () => Promise<Flow>;
     send: string;
   }) => {
     const [flow, setFlow] = useState<Flow>();
     const [error, setError] = useState<string>();
     const started = useRef(false);
     useEffect(() => {
       if (!started.current) {
         started.current = true;
         start().then(setFlow, (error) => setError(String(error)));
       }
     }, []);
     /** The flow's latest event, re-rendering as the handshake moves on. */
     const { event } = useInvitationFlow(flow?.flow);
     if (error) {
       return <p className='cb-error'>{error}</p>;
     }
     if (!flow) {
       return <p className='cb-muted'>Starting the invitation…</p>;
     }
     return (
       <div className='cb-panel'>
         <p>{send}</p>
         <Copyable value={flow.code} />
         <Status event={event} host />
       </div>
     );
   };
   
   /** The guest's side of an invitation: paste the code, then type the authorization code. */
   export const Guest = ({
     label,
     join,
     onDone,
   }: {
     label: string;
     join: (code: string) => Promise<Invitation.Flow>;
     onDone?: () => void;
   }) => {
     const services = useHaloServices();
     const [flow, setFlow] = useState<Invitation.Flow>();
     const { event } = useInvitationFlow(flow);
     useEffect(() => {
       if (event?._tag === 'success' && onDone) {
         const timeout = setTimeout(onDone, 1500);
         return () => clearTimeout(timeout);
       }
     }, [event]);
     if (!flow) {
       return (
         <Prompt
           label={label}
           action='Join'
           onSubmit={(code) => join(code.trim()).then(setFlow)}
         />
       );
     }
   
     /** Sends the authorization code the host shows. */
     const handleAuthenticate = (authCode: string) =>
       Invitation.authenticate(flow, authCode.trim()).pipe(
         Effect.provide(services),
         Effect.runPromise,
       );
   
   

Try it

Alice has Book club; Bob has nothing yet.

1. On Alice’s device, press Invite and copy the code.
2. On Bob’s, press Join, paste it and press Join.
3. Alice’s device now shows an authorization code. Type it into Bob’s and press Send.

Bob’s dropdown now has Book club, and both devices list Alice and Bob under People. Rename one of them and watch the other follow.

What you can do now

You can invite someone into a space and join one, with an authorization code. Next, Your contacts gathers everyone you share a space with.