Cross-language enforcement: publish the token/policy wire spec and ship a TypeScript verifier (big swing)

[dgenio]

Summary

Make weaver capability tokens verifiable beyond Python: precisely specify the token
wire format and verification algorithm (in coordination with weaver-spec), publish
canonical cross-language test vectors, and ship a first non-Python verifier — a
small TypeScript package — so Node-based agents, edge functions, and gateways can
verify kernel-issued tokens.

Why this matters

The agent ecosystem is at least half TypeScript (the MCP reference SDK ecosystem,
serverless tool backends, web agents). Today a weaver token is only meaningful
inside a Python process holding the secret, which caps the kernel's addressable
surface and weakens the federation story. A verifier-only TS package is a deliberate,
bounded first step: verification is small (HMAC + field checks), high-value (any
edge can now enforce "valid weaver token required"), and forces the spec rigor —
canonical serialization, test vectors — that the conformance work (#43, weaver-spec)
needs anyway. It positions the token format as ecosystem infrastructure rather than
a library implementation detail.

Current evidence

• tokens.py: token payload and HMAC scheme exist but the byte-level signing input (canonicalization) is defined only by Python implementation, not by a language-neutral spec.
• The Weaver stack already has a contracts repo (weaver-spec / weaver-contracts on PyPI per the CI stub) — the natural home for the wire spec and vectors.
• Sibling integrations (docs/integrations/*.md) are all Python-side today; no non-Python consumption path exists.

External context

Cross-language token specs live or die on canonical test vectors (the JOSE/PASETO
ecosystems demonstrate both the need and the method); shared-secret HMAC
verification is straightforwardly portable, unlike full kernel semantics.

Proposed implementation

1. Spec first (in weaver-spec): exact canonical serialization of the signed payload,
   field semantics, expiry/constraint evaluation rules, error taxonomy mapping;
   flag any Python-specific serialization quirks found (e.g., dict ordering,
   datetime formats) — fix them kernel-side behind a token version field if needed.
2. Generate canonical test vectors from the Python implementation (valid, expired,
   tampered, wrong-key, constraint-violating) and commit them to the spec repo;
   the kernel's own tests consume the same vectors (single source).
3. Ship @weaver/token-verify (TypeScript, zero-dependency, verify-only — no
   issuance) passing all vectors; document the secret-distribution caveat (shared
   secret; pairs with ISSUE 61's public-key investigation, which would make this
   dramatically safer cross-org).
4. Non-goals: porting policy evaluation, the firewall, or issuance.

AI-agent execution notes

• Inspect first: tokens.py (signing input construction — byte-exact), tests/test_tokens.py, weaver-spec repo structure, the CI conformance stub.
• The dangerous part is canonicalization mismatches — vectors must cover unicode, datetime precision, constraint dict ordering.
• Cross-repo coordination: spec changes land in weaver-spec; flag impact per that repo's process.
• A token format version field (if added) must be inside the signed payload.

Acceptance criteria

• A language-neutral wire spec with committed test vectors exists in the contracts repo.
• Python kernel tests consume the shared vectors (no divergence possible).
• The TS verifier passes all vectors and is published with verify-only scope documented.

Test plan

Shared vector suite in both implementations; CI in both repos consuming the same
files; negative vectors (tampered/expired/wrong-key) mandatory. Run make ci.

Documentation plan

Spec in weaver-spec; kernel docs/capabilities.md interop section; TS package
README; CHANGELOG Added.

Migration and compatibility notes

If canonicalization fixes are needed, gate them behind a token version with a
dual-accept window. Otherwise additive.

Risks and tradeoffs

A second implementation is a standing maintenance commitment — verify-only scope
and shared vectors minimize it. Shared-secret distribution across languages has
real operational caveats; documenting them honestly (and linking ISSUE 61) is part
of the deliverable.

Suggested labels

ecosystem, security, integrations, product