@robono/linked-apps 0.1.0-preview.1 → 0.1.0-preview.2

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+# 0.1.0-preview.2
+
+- Add `beginPairing`, `pollPairing`, and cancellable `waitForPairing`.
+- Codes expire after five minutes and require owner approval in Robono.
+- Bind exchange to the originating client and PKCE verifier, enforce polling backoff,
+  and serialize concurrent polls. Existing callback and messaging APIs remain supported.
+- Pairing uses the existing Robono login. No extra SMS check or callback URL required.
+
 # Changelog
 
 ## 0.1.0-preview.1

package/INTEGRATION.md

@@ -4,16 +4,19 @@ Use a separate registration for development and production. Robono supplies its
 functions URL, client ID and reviewed redirect URI/scopes. Client IDs are public.
 A backend webhook signing secret is confidential and must never enter a mobile bundle.
 
-## Link an account
+## Link an account with a code
+
+Pairing support requires SDK 0.1.0-preview.2 or newer. The currently registered
+client ID is public; users never need a developer account. Pairing-only clients
+use an empty `redirect_uris` list and do not need callback URLs.
 
 ```ts
 import { RobonoLinkedApps, secureTokenStore, nativeCryptoProvider } from '@robono/linked-apps';
 import * as SecureStore from 'expo-secure-store';
 import * as Crypto from 'expo-crypto';
-import { Linking } from 'react-native';
 
-const ot = new RobonoLinkedApps({
-  functionsUrl: config.robonoFunctionsUrl,
+const robono = new RobonoLinkedApps({
+  functionsUrl: 'https://vzoqxavqacydtwypjsrd.supabase.co/functions/v1',
   clientId: config.robonoClientId,
   tokenStore: secureTokenStore(SecureStore, 'robono.linked.account.primary'),
   crypto: nativeCryptoProvider({
@@ -21,31 +24,50 @@ const ot = new RobonoLinkedApps({
     digest: (_, bytes) => Crypto.digest(Crypto.CryptoDigestAlgorithm.SHA256, new Uint8Array(bytes)),
   }),
 });
-const link = await ot.beginLink('com.example.app://robono/callback',
+const pairing = await robono.beginPairing(
   ['account:read', 'messages:read', 'messages:send', 'receipts:write']);
-// Keep the verifier/state in Keychain/Keystore across the app switch.
-await SecureStore.setItemAsync('robono.pending-link', JSON.stringify(link.pending));
-await Linking.openURL(link.authorizationUrl);
-// In your callback handler, after matching the registered route:
-const pending = JSON.parse((await SecureStore.getItemAsync('robono.pending-link'))!);
-await ot.completeLink(callbackUrl, pending);
-await SecureStore.deleteItemAsync('robono.pending-link');
+// Show pairing.userCode with a five-minute expiry indication.
+// Tell the user: Robono > Linked apps > Connect an app > enter this code.
+// Optional: open pairing.verificationAppUrl to take them to Robono.
+await SecureStore.setItemAsync('robono.pending-pair', JSON.stringify(pairing.pending));
+const controller = new AbortController();
+// Abort when this screen closes, the account changes, or the app backgrounds.
+const tokens = await robono.waitForPairing(pairing.pending, controller.signal);
+await SecureStore.deleteItemAsync('robono.pending-pair');
+// Connected. Tokens are already saved by the configured TokenStore.
 ```
 
-The native adapters are dependency-injected: bare React Native can supply equivalent
-Keychain/Keystore and cryptography implementations. Never use Math.random or ordinary
-AsyncStorage for credentials/verifiers. Choose platform key accessibility according
-to your app's background needs; never opt into backup/sync of account secrets.
-
-Register the callback on **both iOS and Android**. Prefer an owned HTTPS universal/app
-link where possible. Private native schemes must be unique reverse-domain names;
-PKCE protects code redemption from interception. Never accept arbitrary callback
-hosts, skip state verification, or copy a Robono phone session into your app.
-
-Only one SDK instance owns a connected account's refresh sequence. Multiple runtimes
-or processes must coordinate access to secure storage. A lost refresh response or
-crash before the rotated pair is persisted may require relinking; retrying a spent
-refresh token revokes the grant. Do not automatically repeat token exchanges.
+If backgrounded while the user opens Robono, cancel polling, preserve pending
+state securely, then resume `waitForPairing` on foreground if it has not expired.
+Use one poller per pairing and one SDK instance per connected account. You can
+call `pollPairing` directly; it returns `pending` or `connected` and updates the
+pending state's interval and next-poll time. Persist those updates if resuming
+across process restarts. Network failures are surfaced: offer a retry with
+backoff while the code remains valid. Never spin on errors.
+
+Robono authenticates the owner using its existing phone session. A signed-out
+user signs in through Robono's normal login first. There is no extra SMS check
+for account linking. The code does not itself authorize access: the user must
+review the app, account, and permissions and choose Allow connection in Robono.
+Never request the user's Robono login code, password, or phone-session token.
+
+The visible code expires after five minutes. The device code and PKCE verifier
+are secrets; never show, log, put them in URLs, or send them to analytics. Native
+clients use Keychain/Keystore; browser/server hosts must supply equivalent secure
+storage. Only the app that initiated pairing can exchange the approved request.
+Do not call completion repeatedly after receiving tokens. If the successful
+exchange response is lost, start a new pairing; a consumed code cannot be reused.
+
+HTTP clients: POST `linked-app-pair` with client_id, scopes, S256 code_challenge
+and code_challenge_method. Poll `linked-app-token` using grant_type
+`urn:ietf:params:oauth:grant-type:device_code`, client_id, device_code and
+code_verifier. Wait at least the returned interval (initially five seconds).
+`authorization_pending` means keep waiting; `slow_down` increases the interval
+by five seconds (up to sixty). Stop on `access_denied`, `expired_token`, or
+`invalid_grant`. A 429 requires backoff. Only a successful response contains tokens.
+
+The older registered-callback `beginLink` / `completeLink` APIs remain supported
+for existing clients. New code pairing requires no callback handler.
 
 ## Display and send
 

package/README.md

@@ -17,8 +17,10 @@ npm --prefix packages/linked-apps test
 
 Use one `RobonoLinkedApps` instance per connected account. Inject a Keychain/Keystore
 `TokenStore` and native `CryptoProvider`; adapters are exported. Browser/server
-runtimes may use WebCrypto. Securely persist pending PKCE verifier/state before
-opening Robono; validate the callback using `completeLink`.
+runtimes may use WebCrypto. Use `beginPairing` to obtain a code, show it to the user, then call
+`waitForPairing` to finish after approval in Robono. Store pending state securely.
+Robono reuses its normal login; account linking adds no SMS verification.
+Registered callback linking remains available for existing clients.
 
 [Integration guide](./INTEGRATION.md) ·
 [API reference](https://robono.com/api-reference-viewer.html?spec=linked-apps) ·
@@ -40,7 +42,7 @@ require relinking because reusing a spent refresh token revokes the grant.
 The official distribution channel is npm. Install this exact preview version:
 
 ```sh
-npm install --save-exact @robono/linked-apps@0.1.0-preview.1
+npm install --save-exact @robono/linked-apps@0.1.0-preview.2
 ```
 
 Preview releases use the `preview` tag. Pin the version and commit your lockfile; review release notes and test before updating. The Robono website does not distribute SDK archives.

package/dist/index.d.ts

@@ -28,6 +28,21 @@ export interface PendingLink {
     state: string;
     expiresAt: string;
 }
+/** Secret pending state: keep in secure storage, never display or log it. */
+export interface PendingPairing {
+    clientId: string;
+    deviceCode: string;
+    verifier: string;
+    expiresAt: string;
+    interval: number;
+    nextPollAt: number;
+}
+export type PairingResult = {
+    status: "pending";
+} | {
+    status: "connected";
+    tokens: Tokens;
+};
 export interface SendMessage {
     conversationId: string;
     messageKind: "text" | "voice" | "image" | "video" | "document";
@@ -58,6 +73,7 @@ export declare class RobonoLinkedApps {
     private readonly options;
     private readonly baseUrl;
     private readonly fetcher;
+    private pairingPolls;
     private refreshPending;
     constructor(options: {
         functionsUrl: string;
@@ -68,6 +84,24 @@ export declare class RobonoLinkedApps {
         timeoutMs?: number;
     });
     private post;
+    /** Show only userCode. The user approves inside their signed-in Robono app. */
+    beginPairing(scopes: Scope[], signal?: AbortSignal): Promise<{
+        userCode: string;
+        verificationUrl: string;
+        verificationAppUrl: string;
+        pending: {
+            clientId: string;
+            deviceCode: string;
+            verifier: string;
+            expiresAt: string;
+            interval: number;
+            nextPollAt: number;
+        };
+    }>;
+    /** Returns pending until approval. Concurrent calls share one token exchange. */
+    pollPairing(pending: PendingPairing, signal?: AbortSignal): Promise<PairingResult>;
+    /** Cancel when leaving the pairing screen. Never polls in the background implicitly. */
+    waitForPairing(pending: PendingPairing, signal: AbortSignal): Promise<Tokens>;
     beginLink(redirectUri: string, scopes: Scope[]): Promise<{
         authorizationUrl: string;
         requestId: string;

package/dist/index.js

@@ -47,6 +47,7 @@ export class RobonoLinkedApps {
     options;
     baseUrl;
     fetcher;
+    pairingPolls = new Map();
     refreshPending = null;
     constructor(options) {
         this.options = options;
@@ -92,6 +93,90 @@ export class RobonoLinkedApps {
             signal?.removeEventListener("abort", cancel);
         }
     }
+    /** Show only userCode. The user approves inside their signed-in Robono app. */
+    async beginPairing(scopes, signal) {
+        if (!scopes.length || scopes.some((scope) => !scopeNames.has(scope))) {
+            throw new Error("Select supported permissions.");
+        }
+        const crypto = this.options.crypto ?? webCryptoProvider();
+        const verifier = hex(crypto.randomBytes(32));
+        const challenge = base64url(await crypto.sha256(new TextEncoder().encode(verifier)));
+        const result = await this.post("linked-app-pair", {
+            client_id: this.options.clientId, scopes,
+            code_challenge: challenge, code_challenge_method: "S256",
+        }, undefined, signal);
+        const interval = Math.max(5, result.interval);
+        return {
+            userCode: result.user_code,
+            verificationUrl: result.verification_uri,
+            verificationAppUrl: result.verification_app_uri,
+            pending: {
+                clientId: this.options.clientId, deviceCode: result.device_code, verifier,
+                expiresAt: result.expires_at, interval, nextPollAt: Date.now() + interval * 1000,
+            },
+        };
+    }
+    /** Returns pending until approval. Concurrent calls share one token exchange. */
+    async pollPairing(pending, signal) {
+        if (pending.clientId !== this.options.clientId ||
+            !Number.isFinite(Date.parse(pending.expiresAt)) ||
+            Date.parse(pending.expiresAt) <= Date.now()) {
+            throw new RobonoLinkedAppError("expired_token", 400);
+        }
+        if (signal?.aborted)
+            throw new RobonoLinkedAppError("cancelled", 400);
+        const existing = this.pairingPolls.get(pending.deviceCode);
+        if (existing)
+            return existing;
+        if (Date.now() < pending.nextPollAt)
+            return { status: "pending" };
+        const operation = (async () => {
+            pending.nextPollAt = Date.now() + Math.max(5, pending.interval) * 1000;
+            try {
+                const wire = await this.post("linked-app-token", {
+                    client_id: this.options.clientId,
+                    grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+                    device_code: pending.deviceCode, code_verifier: pending.verifier,
+                }, undefined, signal);
+                const tokens = await this.save(wire);
+                return { status: "connected", tokens };
+            }
+            catch (error) {
+                if (error instanceof RobonoLinkedAppError &&
+                    ["authorization_pending", "slow_down"].includes(error.code)) {
+                    if (error.code === "slow_down")
+                        pending.interval = Math.min(60, pending.interval + 5);
+                    return { status: "pending" };
+                }
+                throw error;
+            }
+            finally {
+                pending.nextPollAt = Date.now() + Math.max(5, pending.interval) * 1000;
+            }
+        })();
+        this.pairingPolls.set(pending.deviceCode, operation);
+        try {
+            return await operation;
+        }
+        finally {
+            this.pairingPolls.delete(pending.deviceCode);
+        }
+    }
+    /** Cancel when leaving the pairing screen. Never polls in the background implicitly. */
+    async waitForPairing(pending, signal) {
+        while (!signal.aborted) {
+            if (Date.parse(pending.expiresAt) <= Date.now()) {
+                throw new RobonoLinkedAppError("expired_token", 400);
+            }
+            await waitForPoll(Math.max(0, Math.min(pending.nextPollAt, Date.parse(pending.expiresAt)) - Date.now()), signal);
+            if (signal.aborted)
+                break;
+            const result = await this.pollPairing(pending, signal);
+            if (result.status === "connected")
+                return result.tokens;
+        }
+        throw new RobonoLinkedAppError("cancelled", 400);
+    }
     async beginLink(redirectUri, scopes) {
         if (!scopes.length || scopes.some((scope) => !scopeNames.has(scope))) {
             throw new Error("Select supported permissions.");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robono/linked-apps",
-  "version": "0.1.0-preview.1",
+  "version": "0.1.0-preview.2",
   "private": false,
   "description": "User-authorized companion-app access to Robono (development preview)",
   "type": "module",