Site and Extension Handshake

Draft 0.1 — 2 August 2026
This is an architecture specification, not a production cryptographic profile. Algorithms, schemas, and key formats require dedicated security review before release.

Objective

When a participant opens the ANUKA extension on a connected site, the extension should know:

which ANUKA project represents the current origin;
whether the declaration is official and current;
what the site allows the participant to do;
which interface should open;
which data is public, permissioned, or unavailable;
whether information came from the site, ANUKA Network, or the community.

The handshake must not give a website access to extension secrets, browsing history, unrelated account data, or background capabilities.

Trust boundaries

The architecture contains four distinct contexts.

1. Host page

Code controlled by the website and any third-party scripts it has installed.

The host page is not trusted with extension credentials or unrestricted extension APIs.

2. ANUKA Site SDK

A script or package intentionally installed by the website owner.

The SDK may render UI, expose the official project declaration, and call allowed ANUKA APIs. It runs with the privileges of the host page and must therefore be treated as a high-impact third-party dependency.

3. Extension content script

Extension code running alongside the page with limited WebExtension API access.

The content script mediates between the page and the extension service worker. It must validate every message and avoid exposing privileged methods to arbitrary page scripts.

4. Extension service worker and extension pages

The privileged extension context responsible for authentication, permissions, network requests, storage, and opening the side panel or full interface.

The service worker must not trust page messages merely because they were received through a content script.

Handshake goals

The handshake MUST provide:

origin binding;
project-identifier discovery;
protocol-version negotiation;
freshness and replay protection;
capability discovery;
trust-state declaration;
explicit separation between data and executable logic;
auditability;
safe fallback when no handshake exists.

Non-goals

The handshake does not:

prove every company claim true;
authorize arbitrary site code to call extension APIs;
transmit extension authentication tokens to the page;
grant write access merely because a capability is advertised;
replace server-side authorization;
create legal acceptance of resident or commercial agreements.

Recommended discovery mechanisms

A. In-page declaration

The installed Site SDK places a minimal, nonsecret declaration in the DOM:

<meta name="anuka:project" content="prj_01H..." />
<meta name="anuka:presence" content="0.1" />

This is convenient but not sufficient for verified status because any script on the page may modify the DOM.

B. Well-known manifest

The origin serves:

GET /.well-known/anuka

The response binds the origin to a project and contains expiry, capabilities, keys, and a signature or reference to a signed record.

C. Runtime challenge

For higher-assurance interactions, the extension requests a fresh server challenge through ANUKA Network. The site backend signs or proves control over the challenge through an approved method.

Runtime challenge is required when:

enabling a privileged integration;
claiming an organization;
changing owner-controlled public settings;
authorizing payments or stewardship actions;
rotating keys;
recovering a compromised project.

Message flow

Illustrative connected-site flow:

Participant clicks ANUKA action
        ↓
Extension receives temporary activeTab access
        ↓
Content script checks for Site SDK declaration
        ↓
Extension fetches /.well-known/anuka or Network registry
        ↓
Extension validates origin, schema, expiry, signature, and status
        ↓
Site and extension exchange a one-time nonce and capability list
        ↓
Extension opens official Backstage in the correct mode
        ↓
Consequential requests go directly to ANUKA API with participant auth

The page must never receive the participant’s bearer token.

Page-to-content communication

The preferred model is a narrow custom event or window.postMessage() bridge carrying only schema-validated data.

When using postMessage:

the site SDK SHOULD specify an exact target origin where possible;
receivers MUST validate origin and message structure;
receivers SHOULD validate source where meaningful;
messages MUST contain a protocol namespace and version;
messages MUST contain a nonce or correlation identifier;
secrets MUST NOT be placed in page-readable messages;
unrecognized message types MUST be ignored;
payload size and frequency MUST be limited.

MDN warns that any window may send message events and recommends checking the sender’s origin and message syntax. Extension implementations must additionally account for browser-specific isolation behavior.

Illustrative envelope:

{
  "namespace": "network.anuka.presence",
  "version": "0.1",
  "type": "PRESENCE_OFFER",
  "requestId": "req_01H...",
  "nonce": "base64url-random-value",
  "origin": "https://example.com",
  "projectId": "prj_01H...",
  "manifestUrl": "https://example.com/.well-known/anuka",
  "capabilities": ["feedback.create", "roadmap.read"],
  "issuedAt": "2026-08-02T00:00:00Z"
}

This envelope is data, not remote executable code.

Content-to-extension communication

Content scripts SHOULD use the browser runtime messaging API to contact the extension service worker.

The service worker MUST:

verify the sender tab and origin;
reject messages from restricted or unsupported browser pages;
validate the message schema;
compare the asserted origin with the actual tab origin;
verify the manifest independently;
enforce participant and project permissions server-side;
return only data required by the requested interaction.

Capability negotiation

The site advertises capabilities. The extension advertises protocol features it supports.

Example extension hello:

{
  "type": "EXTENSION_HELLO",
  "protocolVersions": ["0.1"],
  "features": [
    "side-panel",
    "active-tab",
    "signed-manifest",
    "participant-auth"
  ],
  "requestId": "req_01H..."
}

The parties select the highest mutually supported compatible version.

Advertised capabilities are invitations to interact, not authorization. Each API call remains subject to authentication, access policy, consent, rate limits, payment state, and abuse controls.

Origin binding

A manifest MUST identify its exact origin, including scheme and hostname. Ports must be included when nondefault.

Clients MUST reject a manifest when:

the manifest origin does not match the active page origin;
HTTPS is required but not used;
the signature is invalid;
the manifest is expired beyond allowed clock skew;
the key is revoked or unknown;
the project is suspended;
a redirect crosses to an unapproved origin;
the response content type is invalid;
the schema version is unsupported.

Subdomains are separate origins unless an explicit parent-domain policy defines otherwise.

Freshness and replay protection

Signed declarations SHOULD include:

issued-at time;
expiration time;
unique manifest identifier;
current key identifier;
previous-manifest reference when replacing a declaration;
revocation or status endpoint.

Interactive handshakes SHOULD include a cryptographically random nonce and a short expiration window.

A nonce MUST be single-use for consequential actions.

Key management

The first implementation should minimize key complexity.

Recommended stages:

Stage 1 — Network-hosted claim

ANUKA verifies domain control and serves an origin-bound registry record. Appropriate for MVP.

Stage 2 — Customer-controlled signing key

The organization signs its Presence Manifest. ANUKA records the relationship between the project, origin, and key.

Stage 3 — Portable credential or attestation

The organization may publish interoperable credentials or attestations for domain control and resident status.

Production design must cover:

key rotation;
compromise recovery;
multiple authorized administrators;
revocation;
custody options;
hardware-backed keys where justified;
organization changes and acquisitions;
domain expiration and reassignment.

Site SDK loading security

A remote site script executes with access to the host page. The loader therefore SHOULD support:

HTTPS only;
immutable version URLs;
Subresource Integrity hashes for pinned versions where operationally feasible;
crossorigin="anonymous" when required for SRI;
strict Content Security Policy documentation;
a minimal bootstrap loader;
explicit release notes and rollback versions;
no eval() or dynamically fetched executable strings;
clear data-endpoint allowlists;
self-hosting for organizations that require it.

Subresource Integrity enables the browser to compare a fetched script with a declared cryptographic hash before execution. Sites choosing an automatically updating loader must understand that a fixed integrity hash and automatic unpinned updates are in tension; ANUKA should offer both pinned and managed channels.

Example pinned loader:

<script
  src="https://cdn.anuka.network/widget/0.1.0/widget.js"
  integrity="sha384-REPLACE_WITH_RELEASE_HASH"
  crossorigin="anonymous"
  data-anuka-project="prj_01H..."
  defer>
</script>

Manifest V3 boundary

The browser extension package MUST contain its executable logic.

Chrome’s Manifest V3 policy permits remote data and configuration but generally prohibits loading or executing remotely hosted logic from the extension. Therefore:

capabilities may be returned as structured data;
UI text, records, metrics, and configuration may be fetched;
JavaScript code must not be fetched and evaluated;
server instructions must not form a hidden interpreter for remote logic;
feature flags may select among logic already shipped in the extension;
extension review must be able to determine the product’s functionality from submitted code.

Authentication boundary

The site, extension, and ANUKA web app MAY share the participant’s ANUKA identity through normal authorization flows, but credentials must remain origin-scoped.

Recommended model:

extension stores its own tokens in extension-controlled storage;
the page uses its own session;
both communicate with ANUKA API independently;
the server links actions through participant and project identifiers;
the page receives only a short-lived, purpose-bound interaction result when needed.

Do not expose extension tokens through DOM attributes, page JavaScript, URL fragments, logs, analytics events, or postMessage payloads.

Restricted pages

Browser extensions cannot inject content scripts into all browser and store pages. Each browser maintains protected origins and internal pages.

The UI MUST gracefully state when ANUKA cannot operate on the current page. It must not attempt to bypass browser restrictions.

Audit events

The system SHOULD record security-relevant events:

project discovery source;
manifest validation outcome;
protocol version selected;
capability invoked;
permission requested and result;
consent state used;
authentication principal;
action requested and server response;
signature or status failure;
revocation or disconnect;
extension and SDK versions.

Audit records should avoid unnecessary browsing-history collection.

Threat model summary

Threat	Primary control
Malicious page impersonates a connected project	Origin-bound manifest and independent validation
Stale or replayed declaration	Expiry, nonce, status, and manifest identifiers
Page steals extension token	Separate auth contexts and no token exposure
Remote server changes extension behavior invisibly	MV3 self-contained logic and typed configuration
Compromised CDN script	Pinned releases, SRI, CSP, rollback, optional self-hosting
Extension reads every page unnecessarily	`activeTab` first and optional host permissions
Fake verified label	Contextual verification policy and signed status
Confused-deputy API call	Server authorization for every consequential action
Message injection	Origin, source, namespace, nonce, and schema validation
Domain changes owner	Claim expiry, monitoring, re-verification, and revocation

Implementation milestones

MVP

activeTab-initiated extension action;
project ID discovery;
ANUKA-hosted origin registry;
official/unclaimed labeling;
public capability list;
side-panel Backstage;
no page access without user action unless explicitly granted.

Connected release

Site SDK runtime declaration;
/.well-known/anuka manifest;
capability negotiation;
signed or network-attested connection state;
GTM adapter;
audit events.

Portable protocol

public schemas;
conformance tests;
customer-controlled signing;
revocation and status endpoints;
agent discovery;
independent compatible clients.

Sources

Verification record

Sources opened and checked: 2 August 2026
Security status: Draft threat model only
Cryptographic review required: Yes
Browser-store policy review required before submission: Yes