siarashield_workspace 0.0.48 → 0.0.52

package/README.md

@@ -10,22 +10,83 @@ Angular integration for CyberSiara **SiaraShield** captcha.
   - `@angular/core >=16.0.0 <22.0.0`
   - `@angular/common >=16.0.0 <22.0.0`
 
-## Quick start (recommended, easiest path)
+## Install
 
-Use this flow first. Most users need only these steps.
+```bash
+npm i siarashield_workspace
+```
 
-1. Install package:
+## Quick setup (recommended)
+
+This is the easiest and most reliable flow. It applies all CSP wiring automatically.
 
 ```bash
-npm i siarashield_workspace
+ng add 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`
+If your `angular.json` does not have a `defaultProject`, pass the project name:
+
+```bash
+ng add siarashield_workspace --project <yourProjectName>
+```
+
+What `ng add` does:
+- 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`
+
+## Manual setup (if you don’t want `ng add`)
+
+### Step 1: Add CSP meta tags in `src/index.html`
+
+Copy/paste:
+
+```html
+<meta name="csp-nonce" content="REPLACE_WITH_NONCE" />
+<meta http-equiv="Content-Security-Policy" content="
+default-src 'self';
+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' '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;
+">
+```
 
-3. Put only your **public key** in Angular environment:
+### Step 2: Provide Angular `CSP_NONCE` (recommended)
+
+In `src/app/app.config.ts`:
+
+```ts
+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...
+  ],
+};
+```
+
+### Step 3: Remove old `cspNonce` plumbing (recommended)
+
+You normally **do not need** to pass `cspNonce` from your component.
+
+Remove these if present:
+- `[cspNonce]="cspNonce"` in the template
+- `protected readonly cspNonce = ...` in the component
+- `(window as any).__cspNonce` usage
+
+## Quick start (component integration)
+
+### 1) Put public key in environment
 
 ```ts
 export const environment = {
@@ -33,19 +94,18 @@ export const environment = {
 };
 ```
 
-4. Render component + submit button in template:
+### 2) Render component + submit button in template
 
 ```html
 <siara-shield
   [publicKey]="environment.siaraShieldPublicKey"
-  [cspNonce]="cspNonce"
   (token)="onCaptchaToken($event)"
 ></siara-shield>
 
 <button type="submit" class="CaptchaSubmit" (click)="onSubmit()">Submit</button>
 ```
 
-5. Check captcha before API submit:
+### 3) Check captcha before API submit
 
 ```ts
 import { Component, ViewChild } from '@angular/core';
@@ -60,7 +120,6 @@ import { SiaraShieldComponent } from 'siarashield_workspace';
 })
 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;
@@ -85,36 +144,16 @@ export class FormComponent {
 }
 ```
 
-6. Keep your submit API logic only in the success branch (`ok === true`).
-
-## Key handling (required)
-
-- **Frontend (Angular): public key only**
-- **Backend (.env or secret store): private key only**
-
-Backend example:
-
-```dotenv
-SIARASHIELD_PRIVATE_KEY=YOUR-PRIVATE-KEY
-```
-
-Never place the private key in Angular code or browser-accessible files.
-
-Get keys from [mycybersiara.com](https://mycybersiara.com).
+## Legacy/optional: passing `cspNonce` explicitly
 
-## Integration rules (important)
+If you already have a server-generated nonce available in code, you can still pass it:
+- Component input: `[cspNonce]="myNonce"`
+- Function API: `initSiaraShield({ ..., cspNonce: myNonce })`
 
-- 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.
+If omitted, the plugin auto-resolves the nonce from `meta[name="csp-nonce"]` or an existing `script[nonce]`.
 
 ## Function API (alternative)
 
-Use this only when component integration is not possible.
-
 Template:
 
 ```html
@@ -136,7 +175,7 @@ export class FormComponent {
   private async initializeCaptcha() {
     await initSiaraShield({
       publicKey: environment.siaraShieldPublicKey,
-      cspNonce: (window as any).__cspNonce || undefined,
+      // cspNonce: 'optional-explicit-nonce',
     });
   }
 
@@ -150,48 +189,45 @@ export class FormComponent {
 }
 ```
 
+## Key handling (required)
+
+- **Frontend (Angular): public key only**
+- **Backend (.env or secret store): private key only**
+
+Backend example:
+
+```dotenv
+SIARASHIELD_PRIVATE_KEY=YOUR-PRIVATE-KEY
+```
+
+Never place the private key in Angular code or browser-accessible files.
+
+Get keys from [mycybersiara.com](https://mycybersiara.com).
+
 ## 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.
+For strict CSP, use a **server-generated nonce per request**.
 
-### Strict policy example (recommended for security)
+### Recommended policy example
 
 ```http
 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-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-<dynamic>' https://embed.mycybersiara.com https://mycybersiara.com https://fonts.googleapis.com https://cdnjs.cloudflare.com;
+style-src-elem 'self' 'nonce-<dynamic>' 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'`:
-
-```ts
-import { getSiaraShieldCspPolicy } from 'siarashield_workspace';
-
-const csp = getSiaraShieldCspPolicy({
-  includeUnsafeInlineScript: true,
-  includeUnsafeInlineStyle: true,
-});
-```
-
 ## Script loading behavior
 
-By default (`loadJQuery: true`) package loads required vendor resources automatically:
-
+By default (`loadJQuery: true`) the package loads:
 - `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`
@@ -200,18 +236,6 @@ Most users should **not** add these script tags manually.
 
 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:
@@ -223,16 +247,6 @@ Default behavior is tuned to avoid requiring a second user click when token arri
   - 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
-
-- 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.
 
 ## Build and pack (maintainers)
 

package/package.json

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