@creativeorange/azure-text-to-speech 2.2.2 → 3.0.0

package/README.md

@@ -0,0 +1,496 @@
+# Azure Text to Speech / Speech to Text
+
+Browser package for Azure Cognitive Services Speech with **temporary authorization tokens**. Permanent Azure subscription keys never enter frontend JavaScript.
+
+Package: `@creativeorange/azure-text-to-speech`  
+Current major version: **3.0.0**
+
+## Why version 3 exists
+
+In version 2, constructors accepted a permanent Azure subscription key and used:
+
+```ts
+SpeechConfig.fromSubscription(key, region);
+SpeechTranslationConfig.fromSubscription(key, region);
+```
+
+That forced the real API key into browser bundles, DevTools, and memory. Anyone who can open the page can extract the key and consume your Azure Speech quota.
+
+Version 3 removes that pattern completely. The permanent key stays on your server. The browser only receives short-lived Azure authorization tokens.
+
+## Architecture
+
+```text
+Browser
+  → your backend token endpoint
+  → Azure issueToken endpoint
+  ← temporary Azure token
+  → Azure Speech SDK (fromAuthorizationToken)
+```
+
+Supported authentication options:
+
+1. `tokenEndpoint` — simple GET endpoint (Craft, classic sites)
+2. `getAuthorizationToken` — custom async provider (Laravel APIs, auth headers, CSRF, etc.)
+
+There is **no** option to pass a permanent subscription key.
+
+## Install
+
+```bash
+npm install @creativeorange/azure-text-to-speech
+```
+
+## Public API
+
+### Text to Speech with `tokenEndpoint`
+
+```ts
+import {TextToSpeech} from '@creativeorange/azure-text-to-speech';
+
+const textToSpeech = new TextToSpeech({
+    tokenEndpoint: '/actions/azure-speech/token',
+    voice: 'nl-NL-FennaNeural',
+    region: 'westeurope',
+});
+
+await textToSpeech.start();
+```
+
+### Text to Speech with a custom provider
+
+```ts
+import {TextToSpeech} from '@creativeorange/azure-text-to-speech';
+
+const textToSpeech = new TextToSpeech({
+    voice: 'nl-NL-FennaNeural',
+    region: 'westeurope',
+    getAuthorizationToken: async () => {
+        const response = await fetch('/api/azure-speech/token', {
+            credentials: 'same-origin',
+            headers: {
+                Accept: 'application/json',
+            },
+        });
+
+        if (!response.ok) {
+            throw new Error('Could not obtain Azure Speech token');
+        }
+
+        return response.json();
+    },
+});
+
+await textToSpeech.start();
+```
+
+### Speech to Text
+
+```ts
+import {SpeechToText} from '@creativeorange/azure-text-to-speech';
+
+const speechToText = new SpeechToText({
+    tokenEndpoint: '/actions/azure-speech/token',
+    region: 'westeurope',
+    sourceLanguage: 'nl-NL',
+    targetLanguage: 'nl',
+});
+
+await speechToText.start();
+```
+
+### Token endpoint response
+
+```json
+{
+    "token": "temporary-azure-token",
+    "region": "westeurope"
+}
+```
+
+### Options
+
+```ts
+type SpeechAuthorization = {
+    token: string;
+    region: string;
+};
+
+type SpeechAuthenticationOptions = {
+    tokenEndpoint?: string;
+    getAuthorizationToken?: () => Promise<SpeechAuthorization>;
+    tokenRequestOptions?: {
+        headers?: Record<string, string>;
+        credentials?: RequestCredentials;
+    };
+    tokenLifetimeMs?: number; // default: 8 minutes
+};
+
+type TextToSpeechOptions = SpeechAuthenticationOptions & {
+    region?: string;
+    voice: string;
+    rate?: number;
+    pitch?: number;
+    url?: string; // lexicon URL
+};
+
+type SpeechToTextOptions = SpeechAuthenticationOptions & {
+    region?: string;
+    sourceLanguage: string;
+    targetLanguage?: string;
+};
+```
+
+Provide **exactly one** of `tokenEndpoint` or `getAuthorizationToken`:
+
+- both → `Provide either tokenEndpoint or getAuthorizationToken, not both.`
+- neither → `A tokenEndpoint or getAuthorizationToken provider is required.`
+
+### Token caching
+
+Tokens are cached in memory:
+
+- fetched on first use
+- reused while still valid
+- refreshed after about **8 minutes** by default (`tokenLifetimeMs`)
+- parallel callers share one in-flight request
+- invalid/empty token or region values throw clear errors
+- tokens are never logged and never included in error events
+
+### Browser events
+
+TTS:
+
+- `COAzureTTSStartedPlaying`
+- `COAzureTTSFinishedPlaying`
+- `COAzureTTSStoppedPlaying`
+- `COAzureTTSPausedPlaying`
+- `COAzureTTSResumedPlaying`
+- `COAzureTTSError` → `{ detail: { error: { message, code? } } }`
+
+STT:
+
+- `COAzureSTTStartedRecording`
+- `COAzureSTTStoppedRecording`
+- `COAzureSTTError` → `{ detail: { error: { message, code? } } }`
+
+Error payloads never contain tokens or authorization headers.
+
+## Migrating from v2 to v3
+
+This is a **breaking** change. The old positional constructor is removed on purpose.
+
+### Old unsafe usage
+
+```ts
+const textToSpeech = new TextToSpeech(
+    window.azureSpeechKey,
+    'westeurope',
+    'nl-NL-FennaNeural',
+    0,
+    0
+);
+```
+
+Or Twig leaking the key into the browser:
+
+```twig
+<script>
+    window.azureSpeechKey = '{{ craft.app.config.general.azureSpeechKey }}';
+</script>
+```
+
+Remove these patterns.
+
+### New safe usage
+
+```ts
+const textToSpeech = new TextToSpeech({
+    tokenEndpoint: '/actions/azure-speech/token',
+    region: 'westeurope',
+    voice: 'nl-NL-FennaNeural',
+    rate: 0,
+    pitch: 0,
+});
+```
+
+### Migration checklist
+
+1. Update the package to `3.x`.
+2. Store `AZURE_SPEECH_KEY` and `AZURE_SPEECH_REGION` server-side only.
+3. Add a backend token endpoint (Craft / Laravel / other).
+4. Replace the old constructor with the options object.
+5. Remove every Twig, JavaScript, Vite, Nuxt, or window variable that contained the subscription key.
+6. Rebuild the frontend.
+7. Confirm in DevTools that the permanent key no longer appears in network responses meant for the page, JS bundles, or globals.
+8. Test TTS, STT, highlighting, pause/resume, chained playback, and prefetching.
+9. **Rotate the previously exposed Azure subscription key.** Treat it as compromised.
+
+## Craft CMS integration
+
+### `.env`
+
+```dotenv
+AZURE_SPEECH_KEY="replace-with-secret-key"
+AZURE_SPEECH_REGION="westeurope"
+```
+
+Never export these values to Twig globals, Vite `define`, or frontend env files.
+
+### Module registration (`config/app.php`)
+
+```php
+<?php
+
+return [
+    'modules' => [
+        'azure-speech' => [
+            'class' => \modules\azurespeech\Module::class,
+        ],
+    ],
+    'bootstrap' => [
+        'azure-speech',
+    ],
+];
+```
+
+With controller ID `token`, the action URL becomes:
+
+```text
+/actions/azure-speech/token
+```
+
+### Token controller
+
+```php
+<?php
+
+namespace modules\azurespeech\controllers;
+
+use Craft;
+use craft\web\Controller;
+use yii\web\Response;
+
+class TokenController extends Controller
+{
+    protected array|bool $allowAnonymous = true;
+
+    public function actionIndex(): Response
+    {
+        $key = Craft::parseEnv('$AZURE_SPEECH_KEY');
+        $region = Craft::parseEnv('$AZURE_SPEECH_REGION');
+
+        if (!$key || !$region) {
+            return $this->asFailure(
+                'Azure Speech configuration is missing.'
+            );
+        }
+
+        $client = Craft::createGuzzleClient();
+
+        try {
+            $response = $client->post(
+                "https://{$region}.api.cognitive.microsoft.com/sts/v1.0/issueToken",
+                [
+                    'headers' => [
+                        'Ocp-Apim-Subscription-Key' => $key,
+                    ],
+                    'timeout' => 10,
+                ]
+            );
+        } catch (\Throwable $exception) {
+            Craft::error(
+                'Could not retrieve an Azure Speech token.',
+                __METHOD__
+            );
+
+            return $this->asFailure(
+                'Speech authorization is temporarily unavailable.'
+            );
+        }
+
+        return $this->asJson([
+            'token' => (string) $response->getBody(),
+            'region' => $region,
+        ]);
+    }
+}
+```
+
+For older Craft/PHP versions where a typed property is undesirable:
+
+```php
+protected $allowAnonymous = true;
+```
+
+Use the property form that matches your Craft and PHP version.
+
+### Frontend initialization
+
+```ts
+import {TextToSpeech} from '@creativeorange/azure-text-to-speech';
+
+const textToSpeech = new TextToSpeech({
+    tokenEndpoint: '/actions/azure-speech/token',
+    region: 'westeurope',
+    voice: 'nl-NL-FennaNeural',
+});
+
+textToSpeech.start().catch((error) => {
+    console.error('Could not initialize text to speech.', error);
+});
+```
+
+```ts
+import {SpeechToText} from '@creativeorange/azure-text-to-speech';
+
+const speechToText = new SpeechToText({
+    tokenEndpoint: '/actions/azure-speech/token',
+    region: 'westeurope',
+    sourceLanguage: 'nl-NL',
+    targetLanguage: 'nl',
+});
+
+speechToText.start().catch((error) => {
+    console.error('Could not initialize speech to text.', error);
+});
+```
+
+### Protecting the Craft token endpoint
+
+A temporary token may appear in the browser. That does **not** mean the endpoint can be public and unlimited.
+
+Recommended controls:
+
+- Craft rate limiting and/or webserver/proxy rate limiting
+- Cloudflare rate limiting when available
+- Authentication when TTS/STT is not meant for anonymous visitors
+- HTTPS only
+- Short server-side timeouts (for example 10 seconds)
+- Azure budget and usage alerts
+- Azure resource networking restrictions when infrastructure allows it
+- Never put the permanent key in responses or logs
+
+**CORS alone is not security.** Endpoints can be called outside a browser with `curl` or scripts. Rate limiting, auth, and Azure monitoring remain necessary.
+
+## Laravel token endpoint
+
+```php
+use Illuminate\Support\Facades\Http;
+use Illuminate\Support\Facades\Route;
+
+Route::get('/api/azure-speech/token', function () {
+    $region = config('services.azure_speech.region');
+
+    $response = Http::timeout(10)
+        ->withHeaders([
+            'Ocp-Apim-Subscription-Key' =>
+                config('services.azure_speech.key'),
+        ])
+        ->post(
+            "https://{$region}.api.cognitive.microsoft.com/sts/v1.0/issueToken"
+        );
+
+    abort_unless($response->successful(), 502);
+
+    return response()->json([
+        'token' => $response->body(),
+        'region' => $region,
+    ]);
+})->middleware('throttle:20,1');
+```
+
+Put this route behind authentication whenever the feature is not public.
+
+Example `config/services.php` entries:
+
+```php
+'azure_speech' => [
+    'key' => env('AZURE_SPEECH_KEY'),
+    'region' => env('AZURE_SPEECH_REGION', 'westeurope'),
+],
+```
+
+Frontend:
+
+```ts
+const textToSpeech = new TextToSpeech({
+    tokenEndpoint: '/api/azure-speech/token',
+    region: 'westeurope',
+    voice: 'nl-NL-FennaNeural',
+});
+```
+
+Or with CSRF / custom headers:
+
+```ts
+const textToSpeech = new TextToSpeech({
+    voice: 'nl-NL-FennaNeural',
+    region: 'westeurope',
+    tokenEndpoint: '/api/azure-speech/token',
+    tokenRequestOptions: {
+        headers: {
+            'X-CSRF-TOKEN': document
+                .querySelector('meta[name="csrf-token"]')
+                ?.getAttribute('content') ?? '',
+        },
+    },
+});
+```
+
+## Existing browser features
+
+Version 3 keeps the existing client behaviour from the development branch:
+
+- play / pause / resume / stop
+- word-boundary highlighting
+- chained playback (`co-tts.next`)
+- audio prefetching
+- lexicons via `url`
+- voice / rate / pitch setters
+- existing custom browser events
+
+## HTML attributes (unchanged)
+
+TTS examples:
+
+```html
+<button co-tts="Hello world">Play</button>
+<button co-tts.pause>Pause</button>
+<button co-tts.resume>Resume</button>
+<button co-tts.stop>Stop</button>
+
+<div id="article" co-tts.highlight co-tts.text="Read this text" co-tts.next="next-block">
+    Read this text
+</div>
+```
+
+STT examples:
+
+```html
+<button co-stt.start="transcript">Start</button>
+<button co-stt.stop>Stop</button>
+<div id="transcript"></div>
+```
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test
+npm run lint
+```
+
+Security sanity checks:
+
+```bash
+grep -R "fromSubscription" src
+grep -R "subscriptionKey" src
+```
+
+Both should return no matches in package source.
+
+## License
+
+MIT