Implement and verify the Human Seal

The receipt

A Human Seal is a small JSON object. The fields below are signed. The standard says personal data is referenced by a stable identifier and never embedded. The reference issuer does this: approver_ref is hsa_ followed by 32 hex characters, a one-way hash of the person's internal id, so a public receipt carries no name or email and the issuer can still recompute it. Seals issued before that change (a small number, all test or internal) carry an email address or a service name instead.

The verification algorithm

Small on purpose, so anyone can reimplement it. If any step fails, the Seal is invalid, and it fails in a way that names the reason.

1. Remove signature_ed25519 and public_key; the rest is the signed core.
2. Canonicalize the core: keys sorted by code point, no whitespace, non-ASCII escaped as lowercase \uXXXX, numbers exactly as written (see the conformance page).
3. Verify the Ed25519 signature over those bytes against public_key.
4. Independently resolve the key from the did document (did:web to https to /.well-known/did.json) and confirm it matches.
5. If you have the action, recompute sha256 of its canonical form and confirm it equals content_hash.

Verify in the browser (client side)

Use the same library the verifier page runs. It parses receipts losslessly and canonicalizes exactly as the reference issuer does.

<script src="https://humanseal.world/assets/hs-verify.js"></script>
const r = await HSVerify.verifyReceipt(receiptJsonText, actionJsonText /* optional */);
// r = { valid: true, approver_ref, decision, ... }  or  { valid: false, reason: "..." }

The exact canonical rules, the test vectors that any implementation must reproduce, and a standalone Python verifier are on the conformance page.

Trust root and interoperability

• The issuer key is published at did:web:humanseal.world, resolvable over HTTPS.
• The receipt is structurally a W3C Verifiable Credential (a signed, tamper-evident claim, verifiable without contacting the issuer).
• The signature algorithm (Ed25519) matches the emerging IETF signed-action-receipt work. The canonical form differs from RFC 8785 in string escaping and number formatting, and is identical for ASCII-only data with integer numbers; see the conformance page.

After a Seal is issued

The endpoints an enforcement point uses. They live on the reference issuer today (fo.flocore.tech).

A Seal's identifier for consume and revocation is sha256: plus the SHA-256 of its signature_ed25519 string. The gate library checks expiry, the expected model digest and the revocation list offline; consuming is the one online step.

Ask a person from your agent

The asking side. One call sends a person the exact action, waits, and returns yes only when a person approved and the Seal verified for this action, this tenant and this payload. Everything else is no.

curl -O https://humanseal.world/sdk/hs-ask.js
curl -O https://humanseal.world/sdk/hs-gate.js
curl -O https://humanseal.world/assets/hs-verify.js
# Node 20 or later, the three files in one folder. The token is a service token with agent scope for your tenant.
const { askAndWait } = require('./hs-ask.js');
const r = await askAndWait({
  base: 'https://fo.flocore.tech', token: process.env.FLOCORE_AGENT_TOKEN, tenant: 'your-tenant',
  actionType: 'pay.supplier', title: 'Pay Acme', payload: { amount: '48200', currency: 'ZAR', payee: 'Acme Supplies' },
  onUrl: (url) => console.error('A person must approve this: ' + url),
});
if (!r.allow) throw new Error(r.decision + ': ' + r.reasons.join('; '));   // fail closed
runTheAction(r.payload);

allow is false for a refusal, an expired or timed out request, a stopped agent, a rejected token, a network failure and a Seal that does not fit the action. Nothing in this library lets the agent approve: the person signs in on the hosted approval page and decides there.

Claude Code: approve tool calls before they run

A PreToolUse hook asks a person for each call it is given. It exits 0 with an allow only for an approved, verified call, and exits 2 (which blocks the call) in every other case, including its own errors.

curl -O https://humanseal.world/sdk/humanseal-claude-hook.js
# in .claude/settings.json (the matcher chooses which tool calls need a person)
{ "hooks": { "PreToolUse": [ { "matcher": "Bash|Write|Edit", "hooks": [
  { "type": "command", "command": "node /path/to/humanseal-claude-hook.js", "timeout": 600 } ] } ] } }
# environment: HS_TOKEN, HS_TENANT, optional HS_BASE, HS_TIER, HS_TIMEOUT_SECONDS, HS_OPEN_CMD

Use it from an agent (MCP)

Two read-only tools that verify a Seal offline: no network, no keys, nothing written. Issuing a Seal is deliberately not offered, because only a signed-in person can issue one.

• humanseal_verify: verifies a receipt's signature and, if you pass the action, that it binds exactly that action.
• humanseal_check_seal: the gate check. The Seal must be valid, an approval, bind this action, match the action type, approver and tenant you expect, and name a signed-in person as approver.

curl -O https://humanseal.world/sdk/humanseal-mcp.js
curl -O https://humanseal.world/sdk/hs-gate.js
curl -O https://humanseal.world/assets/hs-verify.js
# keep the three files in one folder, then add to your MCP client:
{ "mcpServers": { "humanseal": { "command": "node", "args": ["/path/to/humanseal-mcp.js"] } } }