# Shield

Shield turns visitors from the countries you choose away from your static sites, keeps the files beside your pages that should stay private from ever being served, and checks how the workspace itself is set up. Network-level attack protection runs in front of every site, app and function and needs no setting.

The rules are one setting for the whole workspace, built into each static site when it deploys. A change, turning Shield off included, reaches a site on that site's next deploy; saving it changes no site that is already live.

## What each part covers

| Part | What it does | Where |
| --- | --- | --- |
| Country blocking | A visitor from a blocked country gets 403 "Not available in your region". The check runs before the cache, so a cached page never gets past it. | Static sites, at their harakumo.app address and on their own domains |
| File guard | Dotfiles, `.env` files and private keys (`.pem`, `.key`, `id_rsa` and the like) are left out when the site deploys, with a line in the deploy log, and a request for one answers 404. `/.well-known/` stays public. | Static sites |
| HTTPS redirect and security headers | Plain HTTP is redirected to HTTPS, and pages are sent with security headers. | Static sites |
| Network-level attack protection | Always on, because every Harakumo address is served through the edge network. There is no setting for it, and no numbers are shown for it. | Every site, app and function |
| Security checks | A check of the workspace's own records: two-factor, API keys, domains, roles and more (below). | The workspace |

> Country blocking and the file guard work on static sites only. Server apps, worker.js programs and functions are not affected by these settings yet; a server app's deploy log says so when countries are blocked.

## Settings

| Setting | Meaning |
| --- | --- |
| `enabled` | Whether the country list is applied (default on). Turned off, a site blocks nobody from its next deploy. |
| `blockedCountries` | Two-letter country codes whose visitors are refused, such as `["KP"]` (default none). The dashboard takes them comma separated. |

> A value that is not two letters is refused with 400. Check each code before you save it: the United Kingdom is GB, not UK.

## Where to change them

- Dashboard → Shield. Every member can see the settings; an owner or admin changes them.
- `GET /api/services/shield` and `PUT /api/services/shield` (the body is merged over the saved settings).
- An owner's or admin's AI assistant, with `get_service_config` and `update_service_config` for the service `shield`.

> Each static site picks a change up on its next deploy, and the deploy log names the countries it blocks (`Shield: blocking KP`).

## Security checks

Dashboard → Shield also checks the workspace itself, measured from its own records each time you look: a score out of 100, what each check found, and the changes made in the workspace per hour over the last 24 hours (UTC). Every member can see them. The same checks come from `GET /api/security/overview`, the SDK's `hk.security.overview()` and the AI connector's `security_overview` tool.

| Check | What it looks at | In the score |
| --- | --- | --- |
| Owners and admins with two-factor | Whether every owner and admin signs in with two-factor. | Yes |
| Full-access API keys | Active keys that are neither read-only nor limited to one project. | Yes |
| Oldest active key | How old the oldest key that has not been revoked is. | Yes |
| Never-used keys | Active keys that have never made a call. Revoke the ones nobody needs. | Yes |
| Domain verification | Custom domains that are not verified yet. | Yes |
| Owners and admins | How many members hold a role that can change everything. | Yes |
| Environment variables | How many are stored. Anyone with developer access to a project can read its variables. Shown, not scored: storing them is normal. | No |
| End-user sign-in lockouts | Users of your apps locked out after repeated failed sign-ins. | Yes |
| Password hashing | How Harakumo stores members' passwords. Shown, not scored: it is not something you set. | No |
| Sign-in for your apps' users | Whether your apps' users can add a second factor. It is not available yet, so it is shown, not scored. | No |
| Audit activity | Changes recorded in the audit log over the last 7 days. | No |
| API key activity | Which keys were used in the last 24 hours, and the data calls counted today and yesterday (UTC). | No |

## Not yet

- No IP lists, rate limits per site, bot checks or counts of blocked visitors yet.
- Rules are one setting for the whole workspace, not per project, and reach a site on its next deploy rather than at once.
- Country blocking does not reach server apps, worker.js programs or functions.
- No managed rule sets of the kind a web application firewall has.

## Reference

**SDK**

```js
const { score, checks } = await hk.security.overview();   // the workspace's security checks
// Shield's settings have no SDK method yet: use REST or the AI connector.
```

**REST**

```http
GET /api/services/shield · PUT /api/services/shield  { "enabled": true, "blockedCountries": ["KP"] }
GET /api/security/overview                            # the workspace's security checks
```