siarashield_workspace

Simple Angular integration for CyberSiara SiaraShield captcha.

Angular compatibility

• Minimum supported Angular version: 16
• Supported Angular range: 16.x to 21.x
• Peer dependency in package is set to:
  • @angular/core >=16.0.0 <22.0.0
  • @angular/common >=16.0.0 <22.0.0

1) Install

npm i siarashield_workspace

2) Get keys

Get your public/private keys from mycybersiara.com.

3) Put keys in correct place

• Frontend (Angular): public key only
• Backend (.env): private key only

Angular environment example:

export const environment = {
  siaraShieldPublicKey: 'YOUR-PUBLIC-KEY',
};

Backend .env example:

SIARASHIELD_PRIVATE_KEY=YOUR-PRIVATE-KEY

Do not place the private key in Angular environment files, templates, or browser code.

4) Add captcha container in template

<div class="SiaraShield"></div>

Add the CaptchaSubmit class to your submit button:

<button class="CaptchaSubmit"></button>

5) Add TypeScript integration (copy-paste)

You can integrate SiaraShield into any form component, including Login, Contact Us, Signup, Forgot Password, and Lead Form screens.

import { OnInit } from '@angular/core';
import { environment } from '../environments/environment';
import { initSiaraShield, checkSiaraShieldCaptcha } from 'siarashield_workspace';

export class FormComponent implements OnInit {
  ngOnInit() {
    this.initializeCaptcha();
  }

  initializeCaptcha() {
    initSiaraShield({
      publicKey: environment.siaraShieldPublicKey,
      cspNonce: (window as any).__cspNonce || undefined,
    });
  }

  onSubmit() {
    const result = checkSiaraShieldCaptcha();
    if (!result.ok) {
      console.log('Captcha not completed yet');
      return;
    }

    console.log(result.token);
    // API call here
    alert('Form submitted successfully');
  }
}

Keep your submit API logic inside the successful captcha branch.

If your frontend reads the nonce from the DOM instead of window, you can reuse the nonce from an existing script tag:

const nonce = document.querySelector('script[nonce]')?.getAttribute('nonce') || undefined;

The nonce must be generated on the server for each request. The plugin NEVER generates a nonce in the browser.

CSP Compliance (Important)

Inline scripts are blocked by CSP unless you allow them with a nonce or a hash. This package does not execute inline JavaScript and does not use eval(), new Function(), setTimeout(string), setInterval(string), or any other string-based execution path. All scripts are loaded as external resources. Any dynamically created <script> elements are assigned the provided CSP nonce when cspNonce is passed.

For strict CSP deployments:

• Generate the nonce on the server for each request.
• Use the SAME nonce in the Content-Security-Policy header.
• Use the SAME nonce on the <script> tag that loads your Angular app or any direct SiaraShield resource.
• Use the SAME nonce in initSiaraShield({ cspNonce: ... }).
• The plugin NEVER generates a nonce in the browser.
• If a valid CSP nonce is required but not provided, browsers will block script execution and the captcha will fail to load.

Safe CSP example:

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;
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;
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;

Example using the same server-generated nonce in a script tag:

<script nonce="YOUR_NONCE" src="https://embedcdn.mycybersiara.com/CaptchaFormate/CaptchaResources.js"></script>

If your Angular app initializes SiaraShield from the main application bundle, that bundle's <script> tag must use the same nonce value that appears in the CSP header.

getSiaraShieldCspPolicy() and mergeSiaraShieldCspPolicy() only generate a baseline CSP string. These helpers do not inject a nonce and do not apply headers. The server must inject the nonce and must apply the final Content-Security-Policy header. The generated policy must always be reviewed before production use.

The package still works in environments without CSP or with relaxed policies. If your site uses a strict nonce-based CSP, passing the server-generated nonce is required.

jQuery loading behavior

• Default loadJQuery is true.
• If jQuery is not already available, the package loads:
  • https://embedcdn.mycybersiara.com/capcha-temple/js/jquery.min.js
• The package also loads:
  • https://embedcdn.mycybersiara.com/CaptchaFormate/CaptchaResources.js
  • https://embed.mycybersiara.com/CaptchaFormate/SiaraShield_Validation.js
• jQuery and the captcha bootstrap process may create script elements dynamically.
• When cspNonce is provided, all dynamically created script elements created by this package are assigned that nonce.
• This is required for compatibility with strict nonce-based CSP policies.
• If a valid CSP nonce is required but not passed, browsers will block those script loads and the captcha will fail to initialize.
• If your app already loads jQuery, set loadJQuery: false.
• If your app loads jQuery from another CDN, allow that host in script-src and script-src-elem.

Quick troubleshooting

• Captcha not visible -> confirm <div class="SiaraShield"></div> is present.
• CheckCaptcha not available -> ensure initSiaraShield(...) ran and CSP allows the required hosts.
• CSP error in console -> confirm the same server-generated nonce is present in the CSP header, the bootstrapping <script> tag, and initSiaraShield(...).
• Token empty -> check browser console and network calls after clicking submit.

Build and pack (library maintainers)

npm run build:lib
npm run pack:lib