|
| 1 | +# API Design <!-- omit from toc --> |
| 2 | + |
| 3 | +Table of Contents |
| 4 | + |
| 5 | +- [Overview](#overview) |
| 6 | +- [@fission/auth](#fissionauth) |
| 7 | + - [API](#api) |
| 8 | + - [Notes](#notes) |
| 9 | + - [Identifier Providers](#identifier-providers) |
| 10 | + - [Types](#types) |
| 11 | + - [Fission Client](#fission-client) |
| 12 | + - [Agent](#agent) |
| 13 | + - [Channels](#channels) |
| 14 | + - [Auth Protocol](#auth-protocol) |
| 15 | +- [@fission/data](#fissiondata) |
| 16 | + - [Notes](#notes-1) |
| 17 | +- [@fission/compute](#fissioncompute) |
| 18 | +- [Ucan Protocol](#ucan-protocol) |
| 19 | + |
| 20 | +## Overview |
| 21 | + |
| 22 | + |
| 23 | + |
| 24 | +## @fission/auth |
| 25 | + |
| 26 | +### API |
| 27 | + |
| 28 | +```ts |
| 29 | +export type AuthResponse<R> = |
| 30 | + | { |
| 31 | + error: undefined |
| 32 | + result: R |
| 33 | + } |
| 34 | + | { |
| 35 | + error: Error |
| 36 | + result: undefined |
| 37 | + } |
| 38 | + |
| 39 | +interface RegisterCredentials { |
| 40 | + username: string |
| 41 | + email: string |
| 42 | + options: { |
| 43 | + emailRedirectUrl?: string |
| 44 | + } |
| 45 | +} |
| 46 | +interface Credentials { |
| 47 | + username: string |
| 48 | +} |
| 49 | + |
| 50 | +interface Account { |
| 51 | + did: string |
| 52 | + username: string |
| 53 | + email: string |
| 54 | +} |
| 55 | + |
| 56 | +interface Session { |
| 57 | + agent: Agent |
| 58 | + account: Account |
| 59 | + expiresAt: number |
| 60 | + identifierDelegation: Ucan |
| 61 | + accountDelegation: Ucan |
| 62 | +} |
| 63 | + |
| 64 | +interface AuthConfig { |
| 65 | + name?: string // defaults to origin |
| 66 | + debug?: boolean |
| 67 | + identifier: IdentifierProvider |
| 68 | + agent: Agent // Handles signatures, dids, ucans and storage |
| 69 | + client: FissionClient // Handles server requests should be a generic client for a Auth UCAN Protocol |
| 70 | +} |
| 71 | + |
| 72 | +declare class Auth { |
| 73 | + constructor(config: AuthConfig) |
| 74 | +} |
| 75 | + |
| 76 | +interface IAuth { |
| 77 | + new (config: AuthConfig): Auth |
| 78 | + /** |
| 79 | + * Trigger an email flow to register a user |
| 80 | + * Signs a Register UCAN with an Identifier |
| 81 | + */ |
| 82 | + register(credentials: RegisterCredentials): Promise< |
| 83 | + AuthResponse<{ |
| 84 | + account: Account |
| 85 | + }> |
| 86 | + > |
| 87 | + |
| 88 | + /** |
| 89 | + * Used to exchange a code from an email link for a session |
| 90 | + */ |
| 91 | + exchangeCodeForSession(code: string): Promise< |
| 92 | + AuthResponse<{ |
| 93 | + session: Session |
| 94 | + account: Account |
| 95 | + }> |
| 96 | + > |
| 97 | + |
| 98 | + /** |
| 99 | + * Requests an Identifier Delegation and IF NEEDED Server Delegations |
| 100 | + * |
| 101 | + * Should we control Session TTL with Identifier Delegation exp and/or Server Delegation exp? |
| 102 | + */ |
| 103 | + login(credentials: Credentials): Promise< |
| 104 | + AuthResponse<{ |
| 105 | + session: Session |
| 106 | + account: Account |
| 107 | + }> |
| 108 | + > |
| 109 | + |
| 110 | + /** |
| 111 | + * Delete Identifier and server Delegations |
| 112 | + * |
| 113 | + * Should we delete all agent data as well? |
| 114 | + */ |
| 115 | + logout(session: Session): Promise<void> |
| 116 | + |
| 117 | + /** |
| 118 | + * Subscribe to auth state changes |
| 119 | + */ |
| 120 | + onStateChange( |
| 121 | + cb: ( |
| 122 | + state: 'Login' | 'Logout' | 'Register' | 'Expired', |
| 123 | + session: null | Session |
| 124 | + ) => void |
| 125 | + ): UnsubscribeFn |
| 126 | +} |
| 127 | +``` |
| 128 | + |
| 129 | +### Notes |
| 130 | + |
| 131 | +- Should keep tabs in sync when in browser |
| 132 | +- Revocation api ? |
| 133 | + |
| 134 | +### Identifier Providers |
| 135 | + |
| 136 | +Providers SHOULD: |
| 137 | + |
| 138 | +- Depend only on UCAN (did:key, signer) and optionally on a [channel](#channels). They can have other dependencies but they should be environment specific. They SHOULD NOT depend on an [Agent](#agent). |
| 139 | +- Be able to receive a DID and a set of capabilities and return a powerbox style UCAN with those capabilities. |
| 140 | +- Be able to send a root delegation over a [channel](#channels) to another device or origin. (see [Delegated](#types)) |
| 141 | + |
| 142 | +A powerbox style delegation to an Agent should be treated as a Session. |
| 143 | + |
| 144 | +#### Types |
| 145 | + |
| 146 | +- Local: Only exists on device normally sandboxed to an origin (webcrypto, wallet, metamask snap and local passkeys) |
| 147 | +- Synced: Exists on device and is synced with a server (synced passkey) |
| 148 | +- Remote: The identifier lives in another device or origin and it needs a [channel](#channels) (websocket, MessageChannel) to request capabilities and receive UCANs. An example could be a personal lobby or a mobile app (wallet). |
| 149 | +- Delegated: The identifier has a wildcard delegation from a Remote Identifier Provider. Does NOT have the root keypair just a root delegation. This is useful for Phase 0 device link with QR Code. (same as local but with a wildcard delegation) |
| 150 | + |
| 151 | +### Fission Client |
| 152 | + |
| 153 | +Client SHOULD only handle HTTP logic, it should receive UCAN delegations, set bearer tokens according to [Spec](https://github.com/ucan-wg/ucan-http-bearer-token) and handle HTTP requests. |
| 154 | + |
| 155 | +In the future this SHOULD be a generic UCAN-RPC client that can be used for any UCAN-RPC protocol, given a set of Capabilities. |
| 156 | + |
| 157 | +### Agent |
| 158 | + |
| 159 | +DID, UCAN, Storage and Channels |
| 160 | + |
| 161 | +- Depends on a Identifier Provider, DID resolver, Signer, Storage and Channels |
| 162 | +- Should provide persistent storage for UCANs and other data |
| 163 | +- Should provide Agent to Agent communication (see [Channels](#channels)), e.g., to sync WNFS keys |
| 164 | +- Should be able to delegate UCANs to other Agents. |
| 165 | + |
| 166 | +### Channels |
| 167 | + |
| 168 | +- pairing mechanics (qr-code, deep-link, shared id, etc) |
| 169 | +- transport (websocket, MessageChannel) |
| 170 | +- encryption (AWAKE MLS) |
| 171 | + |
| 172 | +Comms channel SHOULD a have a generic implementation that can be reused. |
| 173 | + |
| 174 | +### Auth Protocol |
| 175 | + |
| 176 | +Set of UCAN capabilities necessary for Identifier -> Agent -> Server communication |
| 177 | + |
| 178 | +Agent SHOULD only ask Identifier for capabilities it needs NOT wildcard delegation. |
| 179 | + |
| 180 | +## @fission/data |
| 181 | + |
| 182 | +WNFS |
| 183 | + |
| 184 | +### Notes |
| 185 | + |
| 186 | +- Needs to sync keys, we already have device link in auth, we should have a generic and safe comms channel implementation that can be reused or provided by the agent. |
| 187 | +- |
| 188 | + |
| 189 | +## @fission/compute |
| 190 | + |
| 191 | +IPVM |
| 192 | + |
| 193 | +## Ucan Protocol |
0 commit comments