siarashield_workspace 0.0.48 → 0.0.51

package/README.md

@@ -1,242 +1,87 @@
-# `siarashield_workspace`
+# `siarashield_workspace` (CyberSiara SiaraShield Angular plugin)
 
-Angular integration for CyberSiara **SiaraShield** captcha.
+Angular wrapper for the CyberSiara SiaraShield captcha embed.
 
-## Angular compatibility
-
-- Minimum supported Angular: `16`
-- Supported range: `16.x` to `21.x`
-- Peer dependencies:
-  - `@angular/core >=16.0.0 <22.0.0`
-  - `@angular/common >=16.0.0 <22.0.0`
-
-## Quick start (recommended, easiest path)
-
-Use this flow first. Most users need only these steps.
-
-1. Install package:
+## Install
 
 ```bash
 npm i siarashield_workspace
 ```
 
-2. Ensure Angular environment files exist.
-   - If your project does not have `src/environments`, create:
-     - `src/environments/environment.ts`
-     - `src/environments/environment.prod.ts`
-
-3. Put only your **public key** in Angular environment:
-
-```ts
-export const environment = {
-  siaraShieldPublicKey: 'YOUR-PUBLIC-KEY',
-};
-```
-
-4. Render component + submit button in template:
+## Quick setup (recommended)
 
-```html
-<siara-shield
-  [publicKey]="environment.siaraShieldPublicKey"
-  [cspNonce]="cspNonce"
-  (token)="onCaptchaToken($event)"
-></siara-shield>
-
-<button type="submit" class="CaptchaSubmit" (click)="onSubmit()">Submit</button>
-```
+Run `ng add` to automatically apply the recommended CSP + Angular `CSP_NONCE` wiring into your app:
+- updates `src/index.html` (adds `meta[name="csp-nonce"]` + CSP policy)
+- updates `src/app/app.config.ts` (standalone) or `src/main.ts` (fallback) to provide Angular `CSP_NONCE`
 
-5. Check captcha before API submit:
-
-```ts
-import { Component, ViewChild } from '@angular/core';
-import { environment } from '../environments/environment';
-import { SiaraShieldComponent } from 'siarashield_workspace';
-
-@Component({
-  selector: 'app-form',
-  standalone: true,
-  imports: [SiaraShieldComponent],
-  templateUrl: './form.component.html',
-})
-export class FormComponent {
-  protected readonly environment = environment;
-  protected readonly cspNonce = (window as any).__cspNonce as string | undefined;
-
-  private isSubmitting = false;
-  @ViewChild(SiaraShieldComponent) private readonly captcha?: SiaraShieldComponent;
-
-  onCaptchaToken(token: string) {
-    console.log('SiaraShield token:', token);
-  }
-
-  async onSubmit() {
-    if (this.isSubmitting) return;
-    this.isSubmitting = true;
-    try {
-      const ok = await this.captcha?.checkCaptchaAsync();
-      if (!ok) return;
-
-      // Call your backend API only after captcha success.
-      alert('Form submitted successfully');
-    } finally {
-      this.isSubmitting = false;
-    }
-  }
-}
+```bash
+ng add siarashield_workspace
 ```
 
-6. Keep your submit API logic only in the success branch (`ok === true`).
-
-## Key handling (required)
+If your `angular.json` does not have a `defaultProject`, pass the project name:
 
-- **Frontend (Angular): public key only**
-- **Backend (.env or secret store): private key only**
-
-Backend example:
-
-```dotenv
-SIARASHIELD_PRIVATE_KEY=YOUR-PRIVATE-KEY
+```bash
+ng add siarashield_workspace --project <yourProjectName>
 ```
 
-Never place the private key in Angular code or browser-accessible files.
+## Manual setup (if you don’t want `ng add`)
 
-Get keys from [mycybersiara.com](https://mycybersiara.com).
+### Step 1: Add CSP meta tags in `src/index.html`
 
-## Integration rules (important)
-
-- Choose one style per page:
-  - **Recommended:** `<siara-shield ...>`
-  - **Alternative:** function API
-- Do not mix both styles on the same page.
-- Keep submit button class: `CaptchaSubmit`.
-- Initialize captcha once per page load.
-
-## Function API (alternative)
-
-Use this only when component integration is not possible.
-
-Template:
+Copy/paste (and replace `REPLACE_WITH_NONCE` with your real nonce in production):
 
 ```html
-<div class="SiaraShield"></div>
-<button type="submit" class="CaptchaSubmit" (click)="onSubmit()">Submit</button>
-```
-
-TypeScript:
-
-```ts
-import { environment } from '../environments/environment';
-import { initSiaraShield, checkSiaraShieldCaptcha } from 'siarashield_workspace';
-
-export class FormComponent {
-  ngOnInit() {
-    void this.initializeCaptcha();
-  }
-
-  private async initializeCaptcha() {
-    await initSiaraShield({
-      publicKey: environment.siaraShieldPublicKey,
-      cspNonce: (window as any).__cspNonce || undefined,
-    });
-  }
-
-  onSubmit() {
-    const result = checkSiaraShieldCaptcha();
-    if (!result.ok) return;
-
-    console.log(result.token);
-    // API call here
-  }
-}
-```
-
-## CSP guide
-
-If your app has no strict CSP, default integration works without extra setup.
-
-If your app uses strict nonce-based CSP:
-
-- Generate nonce on server for each request.
-- Use same nonce in:
-  - `Content-Security-Policy` header
-  - script tags loading your Angular app
-  - `cspNonce` option/input
-- Do not generate nonce in browser.
-
-### Strict policy example (recommended for security)
-
-```http
+<meta name="csp-nonce" content="REPLACE_WITH_NONCE" />
+<meta http-equiv="Content-Security-Policy" content="
 default-src 'self';
-script-src 'self' 'nonce-<dynamic>' https://embed.mycybersiara.com https://embedcdn.mycybersiara.com;
-script-src-elem 'self' 'nonce-<dynamic>' https://embed.mycybersiara.com https://embedcdn.mycybersiara.com;
+script-src 'self' 'nonce-REPLACE_WITH_NONCE' https://embed.mycybersiara.com https://embedcdn.mycybersiara.com;
+script-src-elem 'self' 'nonce-REPLACE_WITH_NONCE' https://embed.mycybersiara.com https://embedcdn.mycybersiara.com;
+script-src-attr 'self' 'unsafe-inline';
 connect-src 'self' https://embed.mycybersiara.com https://embedcdn.mycybersiara.com;
-style-src 'self' https://embed.mycybersiara.com https://mycybersiara.com https://fonts.googleapis.com https://cdnjs.cloudflare.com;
+style-src 'self' 'nonce-REPLACE_WITH_NONCE' https://embed.mycybersiara.com https://mycybersiara.com https://fonts.googleapis.com https://cdnjs.cloudflare.com;
+style-src-elem 'self' 'nonce-REPLACE_WITH_NONCE' https://embed.mycybersiara.com https://mycybersiara.com https://fonts.googleapis.com https://cdnjs.cloudflare.com;
+style-src-attr 'self' 'unsafe-inline';
 font-src 'self' https://fonts.gstatic.com https://mycybersiara.com https://cdnjs.cloudflare.com data:;
 img-src 'self' data: https://embed.mycybersiara.com https://embedcdn.mycybersiara.com https://mycybersiara.com;
+">
 ```
 
-### Compatibility policy (easier integration, weaker security)
-
-Use only when customer policy allows `'unsafe-inline'`:
+### Step 2: Provide Angular `CSP_NONCE` in `src/app/app.config.ts`
 
 ```ts
-import { getSiaraShieldCspPolicy } from 'siarashield_workspace';
-
-const csp = getSiaraShieldCspPolicy({
-  includeUnsafeInlineScript: true,
-  includeUnsafeInlineStyle: true,
-});
+import { ApplicationConfig, CSP_NONCE } from '@angular/core';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    {
+      provide: CSP_NONCE,
+      useFactory: () =>
+        document.querySelector('meta[name="csp-nonce"]')?.getAttribute('content') ?? null,
+    },
+    // ...your other providers...
+  ],
+};
 ```
 
-## Script loading behavior
-
-By default (`loadJQuery: true`) package loads required vendor resources automatically:
+### Step 3: Do NOT pass `cspNonce` from your component
 
-- `https://embedcdn.mycybersiara.com/capcha-temple/js/jquery.min.js` (fallback when jQuery not already present)
-- `https://embedcdn.mycybersiara.com/CaptchaFormate/CaptchaResources.js`
-- `https://embed.mycybersiara.com/CaptchaFormate/SiaraShield_Validation.js`
+Remove these from your app code (if present):
+- `[cspNonce]="cspNonce"` in the template
+- `protected readonly cspNonce = document.querySelector(...)` in the component
 
-Most users should **not** add these script tags manually.
+## Usage
 
-If your app already has jQuery, set `[loadJQuery]="false"` (or `loadJQuery: false` in function API).
-
-## Advanced validation options
-
-`checkCaptchaAsync(...)` and `checkSiaraShieldCaptchaAsync(...)` support optional tuning:
-
-- `timeoutMs`
-- `pollIntervalMs`
-- `beforeCheckDelayMs`
-- `retryOnFalseMs` (default `0`)
-- `falseResultTokenWaitMs` (default `900`)
-
-Default behavior is tuned to avoid requiring a second user click when token arrives slightly after first response.
-
-## Quick troubleshooting
-
-- Captcha not visible:
-  - Confirm component is rendered and not hidden.
-  - Confirm submit button has `class="CaptchaSubmit"`.
-  - For function API, confirm `<div class="SiaraShield"></div>` exists.
-- `CheckCaptcha` not available:
-  - Ensure initialization completed.
-  - Ensure CSP allows required hosts and nonce.
-- Token not available immediately:
-  - Use async check methods (`checkCaptchaAsync` / `checkSiaraShieldCaptchaAsync`).
-- CSP errors:
-  - Confirm same server-generated nonce in header, script tags, and `cspNonce`.
-
-## Final checklist
+Template:
 
-- Public key in frontend, private key only in backend.
-- Submit button contains `CaptchaSubmit`.
-- Captcha check runs before submit API call.
-- Only one integration style is used per page.
-- CSP nonce is wired correctly for strict CSP deployments.
+```html
+<siara-shield
+  [publicKey]="environment.siaraShield.publicKey"
+  (token)="onCaptchaToken($event)">
+</siara-shield>
+```
 
-## Build and pack (maintainers)
+## Production note (important)
 
-```bash
-npm run build:lib
-npm run pack:lib
-```
+In production, the nonce must be **generated fresh per page load** and injected into both:
+- `meta[name="csp-nonce"]`
+- CSP policy (`'nonce-<value>'`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "siarashield_workspace",
-  "version": "0.0.48",
+  "version": "0.0.51",
   "description": "Angular wrapper for CyberSiara SiaraShield captcha embed.",
   "schematics": "./schematics/collection.json",
   "ng-add": {