@robono/linked-apps 0.1.0-preview.3 → 0.1.0-preview.4

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+# 0.1.0-preview.4
+
+- Add direct integration through `app` details in SDK configuration. No developer
+  account, website registration, issued client ID or manual activation is needed.
+- Use Robono's public service URL by default. Existing `clientId` integrations and
+  explicitly selected development servers remain supported.
+- Normalize and bind app details to a stable internal identity. Direct integrations
+  use code pairing; user consent, PKCE, access scopes and revocation stay intact.
+- Validate returned identity and preserve pairing/refresh across SDK restarts.
+
 # 0.1.0-preview.3
 
 - `watch()` now uses an authenticated persistent WebSocket and automatic recovery.

package/INTEGRATION.md

@@ -1,17 +1,22 @@
 # Integrating an independent app
 
-Register at https://www.robono.com/linked-apps/manage. Developer signup, email
-verification and two-factor authentication are self-service. Registration returns an
-active client ID and functions URL immediately. No Bridge organization, subscription,
-API key or manual activation is required. Use separate development and production
-registrations. Client IDs are public; each user must still approve account access.
-Live updates use an authenticated connection opened by your SDK. No incoming endpoint or delivery configuration is required.
+Install `@robono/linked-apps@0.1.0-preview.4` and supply your app details in SDK
+configuration. No Robono developer account, website registration, API key, issued
+client ID, callback URL or manual activation is needed. The SDK uses Robono's
+published service address by default. This connects to Robono app accounts, not
+the Robono Bridge network API.
+
+App details are supplied by your app; Robono does not certify ownership of the name
+or URLs. Use accurate names and public HTTPS website/privacy-policy links. Robono
+creates its internal client identifier automatically. Keep these details stable:
+a changed profile has a different identifier and needs new account connections.
+For development, use a distinct app name and separate secure credential storage.
+Your users still approve access inside Robono. Installing the SDK grants no access.
 
 ## Link an account with a code
 
-Use SDK 0.1.0-preview.3 or newer for persistent connections. 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.
+Direct integration requires SDK 0.1.0-preview.4 or newer. Existing integrations
+with registered client IDs remain supported, but new integrations should use `app`.
 
 ```ts
 import { RobonoLinkedApps, secureTokenStore, nativeCryptoProvider } from '@robono/linked-apps';
@@ -19,8 +24,12 @@ import * as SecureStore from 'expo-secure-store';
 import * as Crypto from 'expo-crypto';
 
 const robono = new RobonoLinkedApps({
-  functionsUrl: 'https://vzoqxavqacydtwypjsrd.supabase.co/functions/v1',
-  clientId: config.robonoClientId,
+  app: {
+    name: 'Your App',
+    developerName: 'Your Company',
+    websiteUrl: 'https://example.com',
+    privacyUrl: 'https://example.com/privacy',
+  },
   tokenStore: secureTokenStore(SecureStore, 'robono.linked.account.primary'),
   crypto: nativeCryptoProvider({
     getRandomBytes: Crypto.getRandomBytes,
@@ -61,16 +70,21 @@ 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
+HTTP clients: POST `linked-app-pair` with `app` (name, developerName, websiteUrl,
+privacyUrl), scopes, S256 code_challenge and code_challenge_method. Do not send a
+client_id with app. Save the returned client_id with the pending secret state; no
+separate client-registration call is required. Poll `linked-app-token` using grant_type
+`urn:ietf:params:oauth:grant-type:device_code`, the returned 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.
+The older `clientId` configuration and registered-callback `beginLink` / `completeLink`
+APIs remain supported for existing clients. Do not combine `app` and `clientId`.
+Direct integration uses code pairing and requires no callback handler. The internal
+identifier is public; authorization still depends on PKCE and explicit account approval.
+An app name or client ID is not proof of app ownership.
 
 ## Display and send
 

package/README.md

@@ -1,7 +1,7 @@
 # @robono/linked-apps
 
 Robono's user-authorized messaging API client, for independent applications.
-Developer preview. Register your app at https://www.robono.com/linked-apps/manage to receive an active client ID. Each user must approve their own Robono account connection.
+Developer preview. Install the SDK and supply your app details through `app` in its configuration. No developer account, website registration, issued client ID or manual activation is required. Each user approves their own Robono account connection.
 SDK installation alone does not enable account access.
 
 Supports PKCE account linking, rotating credentials, typed conversations/messages,
@@ -43,9 +43,9 @@ 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.3
+npm install --save-exact @robono/linked-apps@0.1.0-preview.4
 ```
 
 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.
 
-The SDK is covered by the included Robono SDK License Agreement. This package contains no client secret or credentials. Robono supplies the registered client ID and environment URL separately.
+The SDK is covered by the included Robono SDK License Agreement. This package contains no client secret or credentials. The default Robono service URL is built in. Existing registered client IDs remain compatible; new integrations use app details.

package/dist/identity.d.ts

@@ -0,0 +1,13 @@
+/** App-supplied display details, not verified ownership or a credential. */
+export interface AppIdentity {
+    name: string;
+    developerName: string;
+    websiteUrl: string;
+    privacyUrl: string;
+}
+export declare function normalizeAppIdentity(app: AppIdentity): AppIdentity;
+/** Stable identifier derived from display details; never proof of app ownership. */
+export declare function directAppIdentity(app: AppIdentity, sha256: (bytes: Uint8Array) => Promise<Uint8Array>): Promise<{
+    clientId: string;
+    profile: AppIdentity;
+}>;

package/dist/identity.js

@@ -0,0 +1,28 @@
+export function normalizeAppIdentity(app) {
+    if (!app || typeof app !== "object" || Array.isArray(app))
+        throw new Error("Provide your app details.");
+    const label = (value, max) => {
+        if (typeof value !== "string" || !value.trim() || value.length > max || /[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/.test(value))
+            throw new Error("Invalid app details.");
+        return value.trim();
+    };
+    const website = (value) => {
+        const url = new URL(label(value, 2048));
+        if (url.protocol !== "https:" || url.username || url.password || url.hash ||
+            !url.hostname.includes(".") || /^(\d+\.){3}\d+$/.test(url.hostname) || url.hostname.includes(":"))
+            throw new Error("Use a public HTTPS website and privacy-policy URL.");
+        return url.toString();
+    };
+    return { name: label(app.name, 100), developerName: label(app.developerName, 150),
+        websiteUrl: website(app.websiteUrl), privacyUrl: website(app.privacyUrl) };
+}
+/** Stable identifier derived from display details; never proof of app ownership. */
+export async function directAppIdentity(app, sha256) {
+    const profile = normalizeAppIdentity(app);
+    const bytes = await sha256(new TextEncoder().encode(JSON.stringify([
+        "robono-direct-app-v1", profile.name, profile.developerName, profile.websiteUrl, profile.privacyUrl,
+    ])));
+    const hex = Array.from(bytes, b => b.toString(16).padStart(2, "0")).join("");
+    const clientId = `${hex.slice(0, 8)}-${hex.slice(8, 12)}-8${hex.slice(13, 16)}-8${hex.slice(17, 20)}-${hex.slice(20, 32)}`;
+    return { clientId, profile };
+}

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { type AppIdentity } from "./identity.js";
+export type { AppIdentity } from "./identity.js";
 import { type EventPage, type WatchOptions } from "./delivery.js";
 import { type LinkedSocketFactory } from "./stream.js";
 import type { ConversationPage, Message, MessagePage, Receipt, UploadTicket } from "./types.js";
@@ -74,17 +76,23 @@ export declare class RobonoLinkedApps {
     private readonly options;
     private readonly baseUrl;
     private readonly fetcher;
+    private readonly app?;
+    private identityPending?;
     private pairingPolls;
     private refreshPending;
     constructor(options: {
-        functionsUrl: string;
-        clientId: string;
+        functionsUrl?: string;
+        /** Direct integration: app details replace website registration. */
+        app?: AppIdentity;
+        /** Compatibility for existing registered integrations. Use app for new integrations. */
+        clientId?: string;
         tokenStore: TokenStore;
         crypto?: CryptoProvider;
         fetch?: typeof fetch;
         timeoutMs?: number;
         webSocket?: LinkedSocketFactory;
     });
+    private clientIdentity;
     private post;
     /** Show only userCode. The user approves inside their signed-in Robono app. */
     beginPairing(scopes: Scope[], signal?: AbortSignal): Promise<{

package/dist/index.js

@@ -1,3 +1,4 @@
+import { directAppIdentity, normalizeAppIdentity } from "./identity.js";
 import { waitForPoll } from "./delivery.js";
 import { consumeStream } from "./stream.js";
 export * from "./types.js";
@@ -47,11 +48,16 @@ export class RobonoLinkedApps {
     options;
     baseUrl;
     fetcher;
+    app;
+    identityPending;
     pairingPolls = new Map();
     refreshPending = null;
     constructor(options) {
         this.options = options;
-        const url = new URL(options.functionsUrl);
+        if (Boolean(options.app) === Boolean(options.clientId))
+            throw new Error("Provide app details or an existing clientId, not both.");
+        this.app = options.app ? normalizeAppIdentity(options.app) : undefined;
+        const url = new URL(options.functionsUrl ?? "https://vzoqxavqacydtwypjsrd.supabase.co/functions/v1");
         if (url.username || url.password || url.search || url.hash ||
             !(url.protocol === "https:" ||
                 (url.protocol === "http:" &&
@@ -61,6 +67,15 @@ export class RobonoLinkedApps {
         this.baseUrl = url.toString().replace(/\/$/, "");
         this.fetcher = options.fetch ?? globalThis.fetch;
     }
+    clientIdentity() {
+        if (this.options.clientId)
+            return Promise.resolve(this.options.clientId);
+        if (!this.identityPending) {
+            const crypto = this.options.crypto ?? webCryptoProvider();
+            this.identityPending = directAppIdentity(this.app, bytes => crypto.sha256(bytes)).then(result => result.clientId);
+        }
+        return this.identityPending;
+    }
     async post(endpoint, body, token, signal) {
         const controller = new AbortController();
         const cancel = () => controller.abort();
@@ -102,23 +117,25 @@ export class RobonoLinkedApps {
         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,
+            ...(this.app ? { app: this.app } : { client_id: await this.clientIdentity() }), scopes,
             code_challenge: challenge, code_challenge_method: "S256",
         }, undefined, signal);
+        if (this.app && result.client_id !== await this.clientIdentity())
+            throw new RobonoLinkedAppError("invalid_client_identity", 400);
         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,
+                clientId: await this.clientIdentity(), 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 ||
+        if (pending.clientId !== await this.clientIdentity() ||
             !Number.isFinite(Date.parse(pending.expiresAt)) ||
             Date.parse(pending.expiresAt) <= Date.now()) {
             throw new RobonoLinkedAppError("expired_token", 400);
@@ -134,7 +151,7 @@ export class RobonoLinkedApps {
             pending.nextPollAt = Date.now() + Math.max(5, pending.interval) * 1000;
             try {
                 const wire = await this.post("linked-app-token", {
-                    client_id: this.options.clientId,
+                    client_id: await this.clientIdentity(),
                     grant_type: "urn:ietf:params:oauth:grant-type:device_code",
                     device_code: pending.deviceCode, code_verifier: pending.verifier,
                 }, undefined, signal);
@@ -178,6 +195,8 @@ export class RobonoLinkedApps {
         throw new RobonoLinkedAppError("cancelled", 400);
     }
     async beginLink(redirectUri, scopes) {
+        if (this.app)
+            throw new Error("Direct integrations use beginPairing; redirect linking requires an existing registered clientId.");
         if (!scopes.length || scopes.some((scope) => !scopeNames.has(scope))) {
             throw new Error("Select supported permissions.");
         }
@@ -185,7 +204,7 @@ export class RobonoLinkedApps {
         const verifier = hex(crypto.randomBytes(32)), state = hex(crypto.randomBytes(32));
         const challenge = base64url(await crypto.sha256(new TextEncoder().encode(verifier)));
         const result = await this.post("linked-app-authorize", {
-            client_id: this.options.clientId,
+            client_id: await this.clientIdentity(),
             redirect_uri: redirectUri,
             scopes,
             state,
@@ -196,7 +215,7 @@ export class RobonoLinkedApps {
             authorizationUrl: result.authorization_url,
             requestId: result.request_id,
             pending: {
-                clientId: this.options.clientId,
+                clientId: await this.clientIdentity(),
                 redirectUri,
                 verifier,
                 state,
@@ -206,7 +225,7 @@ export class RobonoLinkedApps {
     }
     async completeLink(callback, pending) {
         const url = new URL(callback), expected = new URL(pending.redirectUri);
-        if (pending.clientId !== this.options.clientId ||
+        if (pending.clientId !== await this.clientIdentity() ||
             Date.parse(pending.expiresAt) <= Date.now() ||
             url.protocol !== expected.protocol || url.host !== expected.host ||
             url.pathname !== expected.pathname ||
@@ -225,7 +244,7 @@ export class RobonoLinkedApps {
             throw new RobonoLinkedAppError("invalid_callback", 400);
         }
         return this.save(await this.post("linked-app-token", {
-            client_id: this.options.clientId,
+            client_id: await this.clientIdentity(),
             grant_type: "authorization_code",
             redirect_uri: pending.redirectUri,
             code,
@@ -253,7 +272,7 @@ export class RobonoLinkedApps {
                 throw new RobonoLinkedAppError("not_connected", 401);
             try {
                 return await this.save(await this.post("linked-app-token", {
-                    client_id: this.options.clientId,
+                    client_id: await this.clientIdentity(),
                     grant_type: "refresh_token",
                     refresh_token: tokens.refreshToken,
                 }));

package/package.json

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