# Native Wire reference

This page is a compact index for agents and implementers. The normative source is
[`docs/native-wire-v1.md`](https://github.com/RusticStack/lockwell/blob/main/docs/native-wire-v1.md); the complete machine
contract is [`/native-wire-v1.json`](/native-wire-v1.json). Both are versioned with the repository. LNW/1 is experimental,
opt-in, and disabled by default.

## Envelope

| Item | Value |
| --- | --- |
| Magic | ASCII `LKW1` (`4c4b5731`) |
| Version | `1` |
| Byte order | Unsigned big-endian |
| Header | 40 bytes |
| Body | metadata TLVs, payload, CRC32C (4 bytes) |
| Text | shortest-form UTF-8, NUL-free |
| Unknown optional field | Skip |
| Unknown critical field | Reject the stream (`UNSUPPORTED_FIELD`) |
| Downgrade / code reuse | Forbidden |

Header offsets are fixed and must not be inferred from a language ABI:

| Offset | Size | Field |
| ---: | ---: | --- |
| 0 | 4 | magic |
| 4 | 2 | version |
| 6 | 1 | frame type |
| 7 | 1 | flags |
| 8 | 8 | connection sequence |
| 16 | 8 | request ID |
| 24 | 4 | stream ID |
| 28 | 2 | operation/error/control code |
| 30 | 2 | reserved (zero) |
| 32 | 4 | metadata length |
| 36 | 4 | payload length |

## Defaults and security

| Limit or policy | Default |
| --- | --- |
| Metadata / DATA payload / frame | 64 KiB / 1 MiB / 1,114,156 bytes |
| Streams / connections | 128 / 1,024 |
| Stream / connection window | 4 MiB / 16 MiB |
| Auth skew | 300 seconds (maximum 5 minutes) |
| Replay state | 1,024 principals × 256 nonces per principal |
| Upload admission | `security.max_concurrent_uploads = 128`, process-wide |
| Upload idle / maximum duration | 2 minutes / 24 hours per stream |
| Auth retry hint maximum | 600,000 ms |
| Non-loopback TLS | TLS 1.3 + hostname verification |

User metadata is an ordered, duplicate-preserving user namespace. Internal SSE-C and Object Lock fields are typed and
separate. The effective lockwelld mask excludes `SSE_C` (128); use S3 for genuine SSE-C. Admin bit 16 and operation range
`0x1000`–`0x10ff` are reserved and unimplemented.

## Frame types

| Code | Type | Role |
| ---: | --- | --- |
| `0x01` | HELLO | Client version, capabilities, receive limits |
| `0x02` | WELCOME | Server selection and intersection |
| `0x03` | AUTH | Access-key timestamp, nonce, transcript proof |
| `0x04` | AUTH_OK | Tenant, session, expiry, capabilities, effective limits |
| `0x05` | AUTH_ERROR | Bounded authentication failure |
| `0x10` | REQUEST | Starts one operation on an odd client stream |
| `0x11` | DATA | Flow-controlled bytes |
| `0x12` | END | Closes one direction |
| `0x13` | CANCEL | Cancels the stream context |
| `0x20` | RESPONSE | Starts a successful response |
| `0x21` | ERROR | Typed terminal response |
| `0x30` | WINDOW_UPDATE | Grants stream or connection credit |
| `0x31` / `0x32` | PING / PONG | Eight opaque liveness bytes |
| `0x33` | GOAWAY | Drain or protocol reason and last accepted stream |
| `0x34` | CLOSE | Authenticated close acknowledgement |

## Capabilities

| Bit | Name | Advertised by lockwelld |
| ---: | --- | --- |
| 1 | BUCKETS | yes |
| 2 | OBJECTS | yes |
| 4 | PAGINATION | yes |
| 8 | MULTIPART | yes |
| 16 | VERSIONING | yes |
| 32 | OBJECT_LOCK | yes |
| 64 | TAGS | yes |
| 128 | SSE_C | **no** (no enforced native path) |
| 256 | SIGNED_CAPABILITY | yes |
| 512 | TRACE_CONTEXT | yes |
| 1024 | CORS | yes |
| 2048 | NOTIFICATIONS | yes |
| 65536 | ADMIN (reserved) | **no** |

## Operations

| Code range | Operations | Required capability |
| --- | --- | --- |
| `0x0001`–`0x0002` | `CAPABILITIES`, `READINESS` | authenticated discovery |
| `0x0100`–`0x0105` | bucket CRUD and versioning | BUCKETS |
| `0x0200`–`0x0207` | object CRUD, ranges, copy, versions, batch delete | OBJECTS |
| `0x0300`–`0x0305` | multipart create/part/list/complete/abort/list | MULTIPART |
| `0x0400`–`0x0402` | tags get/put/delete | TAGS |
| `0x0500`–`0x0503` | retention and legal hold | OBJECT_LOCK |
| `0x0600` | signed capability mint | SIGNED_CAPABILITY |
| `0x0700`–`0x0702` | bucket CORS get/put/delete | CORS |
| `0x0710`–`0x0712` | bucket webhook notifications get/put/delete | NOTIFICATIONS |

Clients must not send an operation until its capability is selected. The complete field and document schemas are in the
JSON registry; response metadata includes status, ETag, version, length/type, request ID, traceparent, timestamps,
delete-marker, retention/legal-hold, and ordered user metadata.

## Errors and retry contract

| Code | Name | Typical handling |
| ---: | --- | --- |
| `0x0103` | AUTH_REPLAY | terminal; do not retry the proof |
| `0x0300` | RATE_LIMITED | retry only from a fresh connection with fresh credentials/proof when marked retryable |
| `0x0301` | UNAVAILABLE | bounded caller retry when operation/body is replay-safe |
| `0x0302` | DEADLINE_EXCEEDED | terminal for the stream; partial upload state is removed |
| `0x0303` | CANCELLED | caller cancellation; no implicit replay |
| `0x0204` / `0x0205` | RETENTION_DENIED / LEGAL_HOLD_DENIED | authorization/policy denial |
| `0x0207` / `0x0208` | CHECKSUM_MISMATCH / TOO_LARGE | fix input or limits; do not retry unchanged |

`AUTH_ERROR` fields are `retryable` (required bool), `retryAfterMillis` (optional, ≤600000), and bounded `message` (≤512
bytes). Error frames contain safe messages and correlation only; secrets and payloads are never reflected.

## Implementations and source links

- [Native-wire architecture and rollout](/guide/native-wire)
- [`@kelphect/sdk-native` guide](/sdks/bun-native) (Node 22+, Bun 1.4+; browser denied)
- [`lockwellwire` Go client](/sdks/go) (`github.com/RusticStack/lockwell-sdk-go/lockwellwire`; raw LNW/1, server-only)
- [Spring Boot starter guide](/sdks/java-spring-wire) (JDK 25, Spring Boot 4.1.1)
- [Raw protocol Markdown on GitHub](https://github.com/RusticStack/lockwell/blob/main/docs/native-wire-v1.md)
- [Shared fixtures](https://github.com/RusticStack/lockwell-sdk-go/tree/main/tests/native-wire)