SDK-API-Referenz

                      
                      interface VerifyOptions {
  secret?: string;        // HS256-Schlüssel (per-App oder geteilt). Bei HS256-Prüfung erforderlich
  publicKey?: string;     // RS256-PEM-Public-Key. Bei RS256-Prüfung erforderlich (Roadmap)
  audience: string;       // Erweiterungs-App-Host, muss gleich dem Token-aud sein (erforderlich)
  issuer?: string;        // Standard 'gptbots-workspace'
  leewaySeconds?: number; // Toleranz für Uhrenabweichung (Sekunden), Standard 30
  algorithms?: ('HS256' | 'RS256')[]; // Standard ['HS256']
}

interface WorkspaceIdentity {
  accountId: string;                  // = JWT sub
  role: 'OWNER' | 'ADMIN' | 'MEMBER'; // unbekannte Werte werden zu MEMBER normalisiert
  workspaceId: string;                // = JWT workspace_id
  username?: string; email?: string; avatar?: string; appName?: string;
  issuedAt?: number;   // = iat (Sekunden)
  expiresAt?: number;  // = exp (Sekunden)
}

                    

                      
                      interface ExchangeWorkspaceCodeOptions {
  tokenUrl: string;      // /token-Endpunkt der Plattform (absolute URL)
  code: string;          // der beim Callback erhaltene einmalige Autorisierungscode
  codeVerifier: string;  // der zum code_challenge passende PKCE-verifier
  fetch?: typeof fetch;  // injizierbares fetch (Tests/alte Laufzeiten); Standard globales fetch
  timeoutMs?: number;    // Anfrage-Timeout, Standard 10000; 0 zum Deaktivieren übergeben
}

interface WorkspaceCodeExchangeResult {
  wsa: string;           // das signierte wsa, an verifyWsa übergeben
  tokenType?: string;    // 'Bearer'
  expiresIn?: number;    // Gültigkeit des wsa (Sekunden)
}

                    

                      
                      import { verifyWsa, WsaVerificationError } from '@gptbots/workspace-extension-verify';

export function requireWorkspaceIdentity(secret: string, audience: string) {
  return (req, res, next) => {
    try {
      req.identity = verifyWsa(req.body.wsa, { secret, audience });
      next();
    } catch (e) {
      const code = e instanceof WsaVerificationError ? e.code : 'Error';
      res.status(401).json({ code });
    }
  };
}

                    

                      
                      interface ConsumeHandoffOptions {
  exchangeUrl: string;   // Backend-Prüfschnittstelle der Erweiterungs-App
  fetch?: typeof fetch;  // injizierbar
  search?: string;       // Standard location.search
  paramName?: string;    // Standard 'wsa'
  strip?: boolean;       // Standard true (nur bei Erfolg entfernen)
}

                    

                      
                      interface StartWorkspaceLoginOptions {
  authorizeUrl: string;  // /authorize-Endpunkt der Plattform (absolute URL)
  clientId: string;      // app home URL der Erweiterungs-App
  redirectUri: string;   // Callback-Adresse, host muss dieselbe Domain wie clientId haben
  state?: string;        // standardmäßig automatisch generierter 16-Byte-Zufalls-CSRF-state
  workspaceId?: string;  // vorausgewählter Workspace, überspringt die Organisationsauswahlseite
  storage?: StorageLike; // Standard sessionStorage
  redirect?: (url: string) => void; // Standard location.assign
  navigate?: boolean;    // false = nur URL bauen, nicht weiterleiten (popup/Tests)
}
interface WorkspaceLoginRequest { url: string; state: string; codeVerifier: string; }

                    

                      
                      interface AuthorizeCallback { code: string; state: string | null; codeVerifier: string; }

                    

                      
                      interface CompleteWorkspaceLoginOptions {
  exchangeUrl: string;   // Ihre eigene Backend-Austauschschnittstelle
  fetch?: typeof fetch;
  search?: string;       // Standard location.search
  storage?: StorageLike; // Standard sessionStorage
  strip?: boolean;       // Standard true
}

                    

                      
                      unzip workspace-extension-sdk-0.1.0.zip
# Beide Pakete sind bereits mit dist vorgebaut (main=dist/index.js, types=dist/index.d.ts)
npm i ./workspace-extension-sdk/packages/verify   # Backend
npm i ./workspace-extension-sdk/packages/browser  # Frontend

                    

                      
                      cd workspace-extension-sdk
npm install
npm run build       # tsc → dist je Paket
npm test            # node --test (keine externen Testabhängigkeiten, benötigt Node ≥ 22.6 zum direkten Ausführen von .ts)
npm run type-check  # tsc --noEmit