mirror of https://github.com/zap-proto/go.git synced 2026-10-30 15:05:00 +00:00

Files

T

zeekay a1bf2bfa1e feat: RPC/interfaces codegen + cap spec-conformance (SPEC §2.3/§3) + rebrand finish

zapgen — interface (RPC) support:
- Parse `interface` decls (brace + whitespace forms, one parser) with
  1-based auto-assigned method ordinals; methods take ≤1 struct request and
  (after `returns`) ≤1 struct response, matching the spec README grammar.
- desugar: `interface` opens a whitespace block; method lines pass through
  verbatim (no @N). Block headers now honored only at file scope, so a
  struct field NAMED `interface`/`struct` stays a field (H4 preserved).
- emit: per interface a 1-based ordinal table, a typed Client over a
  Channel seam, and an abstract Handler + Dispatch<Iface> ordinal router,
  all over the new runtime call envelope. Method names exported.
- New `rpc` package: the ZAP call envelope (BuildRequest/ParseRequest,
  BuildResponse/ParseResponse, Call, Response, status codes), byte-compatible
  with the other runtimes' transport envelopes (Version2 header + router
  msgType flags). Adds zap.NewBuilderV2.
- examples/echo: generated service + end-to-end client↔dispatch↔handler test
  covering request/response, void, no-request, bare, handler-error, and
  unknown-ordinal paths. Golden fixtures for the interface codegen.

cap — reconcile to SPEC v1.1:
- B3 signature scope: sign SPEC §3 canonical bytes (Capability[0..164) ||
  canonical(Caveats), Kind:u32||len:u32||Value), via Cap.CanonicalBytes —
  one definition shared by signer and verifier; excludes Sig and heap
  indirection so caps verify cross-language. CapID = Hash32(Canonical||Sig).
- B2 delegation gate: define cross-cutting Permission bits (PermAttenuate
  1<<32, PermAudit, PermRoot); enforce SPEC §2.3 step 3d in VerifyChain and
  at mint time in Attenuate (refuse a cap the verifier would reject).
- B4/B6: VerifyRevocation is scheme-aware (dispatches on the tag byte);
  verifySig fails closed on SchemeReserved/unknown instead of falling back
  to ed25519. Verifier.VerifyRevocation added for PQ revocations.
- spec_test.go covers all four.

Rebrand finish + docs:
- Zero capnp/Cap'n Proto and zero hanzo/avalabs/capnproto.org tokens in
  zap-native source (zap.go doc neutralized; cap doc-comment brand refs
  generalized). LLM.md refreshed: zapgen shipped (not "forthcoming"), rpc
  package, interface DSL, cap signature scope. Ignore the agents example
  binary.

go build ./... and go test ./... -count=1 pass; race-clean on changed pkgs.

2026-06-20 00:02:22 -07:00

4.4 KiB

Raw Permalink Blame History

zap-proto/go/cap

What this is

The Go runtime for ZAP capabilities. A Cap is a signed, attenuable token of authority over a Target, granted to a Holder, by an Issuer. Caps form chains via the Parent field; VerifyChain walks back to a root checking signature, expiry, revocation, target invariance, and monotonically-widening permissions.

Import path: github.com/zap-proto/go/cap. Package name: cap.

Wire shape

Canonical ZAP framing — 16-byte ZAP header (magic + version + root offset + size) followed by the Capability object's fixed section (3572 bytes at v1.1: Kind…Sig at the offsets declared in capabilities.zap) followed by the Caveats list elements (each a full ZAP sub-message length-prefixed by AddObjectBytes). No "ZCAP" magic; no hand-rolled length prefixes. The wire bytes are produced by the generated NewCapabilityView builder and read by the generated CapabilityView zero-copy view in capabilities_zap.go — cap.go is a thin idiomatic wrapper exposing the public Cap type.

Signature scope: SPEC §3 canonical bytes — Capability[0..164) (Kind through the Caveats list pointer) concatenated with each Caveat encoded Kind:u32-LE || len(Value):u32-LE || Value in list order. Cap.CanonicalBytes() produces them; the signer and verifier share that one definition (no "build relaxed, verify strict" asymmetry), and the encoding excludes Sig and the ZAP heap-indirection bytes so it is identical across language runtimes. CapID = Hash32(CanonicalBytes || Sig). Schema lives at github.com/zap-proto/zap-spec/capabilities.zap.

capabilities_zap.go is go generate-regenerable:

zapgen -single -type-suffix=View -out . path/to/capabilities.zap

API

Wrap(b []byte) (Cap, error) — parse a buffer (no allocation).
Issue(in Issuance, signer Signer) (Cap, error) — mint a root cap.
Attenuate(parent, holder, perms, caveats, expiresAt, signer) — derive a child. Permissions intersect with parent's, expiry can only shrink, signer must equal parent.Holder(), and the parent must carry PermAttenuate (or be KindDelegate) — else ErrNotDelegable.
Cap.CanonicalBytes() — the SPEC §3 signing scope (see Wire shape).
Verifier{IsRevoked, IssuerKey, SchemeVerify}.Verify(c, now) — single-cap checks (signature fail-closed on unknown scheme).
Verifier.VerifyChain(leaf, chain, op, target, holder, now) — full-chain validation including op-against-mask and the delegation gate.
Revoke(c, now, signer) / VerifyRevocation(r, pub) / Verifier.VerifyRevocation(r, pub) — revocation (scheme-aware).

Crypto

Hash: SHA-256 (BLAKE3 swap-point planned — see Hash32 comment). Signature: pluggable Signer interface (sign side) + Verifier.SchemeVerify hook (verify side). The wire scheme is selected by the algorithm tag at Sig[AlgTagOffset]; dispatch is fail-closed (SPEC §2.3 step 3c) — a tag the verifier does not implement, or SchemeReserved (0x00), is refused. Ed25519 is the built-in bootstrap (mandatory-to-implement); a consumer wires ML-DSA-65 / hybrid / secp256k1 by supplying a SchemeVerify hook (and the matching Signer). Tests use the in-package Ed25519Signer (64-byte sig padded to the SigSize-byte footer width, scheme tag SchemeEd25519 at Sig[AlgTagOffset]).

Permission bits: the cross-cutting top-32 bits are defined in perms.go (PermAttenuate 1<<32, PermAudit 1<<33, PermRoot 1<<63). Attenuation is gated on PermAttenuate (or KindDelegate) at BOTH mint time (Attenuate) and verify time (VerifyChain, SPEC §2.3 step 3d).

Layout

capabilities_zap.go  Generated zero-copy views + builders (DO NOT EDIT)
cap.go               Public Cap wrapper + accessors + Scheme + ID + Hash32
canonical.go         CanonicalBytes — the SPEC §3 signing scope
perms.go             Cross-cutting Permission bits (PermAttenuate/Audit/Root)
issue.go             Issuance, Issue, Attenuate, buildCapBytes
verify.go            Verifier, Verify, VerifyChain (delegation gate)
revoke.go            Revocation, Revoke, VerifyRevocation,
                       EncodeRevocation, DecodeRevocation
signer.go            Signer interface + Ed25519Signer test stub
cap_test.go          Round-trip, attenuation, chain walk, revocation, caveats
spec_test.go         SPEC conformance: delegation gate, canonical bytes,
                       scheme-aware + fail-closed signature dispatch

Test

go test ./cap/

All tests must pass clean.

4.4 KiB Raw Permalink Blame History