@owlmeans/basic-envelope 0.1.18-rc.3 → 0.1.18-rc.30

package/README.md

@@ -11,7 +11,7 @@ Type-safe message envelope with TTL, signing, and Base64 encoding for cross-serv
 ## Installation
 
 ```bash
-bun add @owlmeans/basic-envelope
+bun add @owlmeans/basic-envelope@^0.1.18-rc.30
 ```
 
 ## Usage
@@ -80,7 +80,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
 your project's skill store (`.agents/skills/`):
 
 ```sh
-npx @owlmeans/agent-skills
+npx @owlmeans/agent-skills@^0.1.18-rc.31
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/basic-envelope",
-  "version": "0.1.18-rc.0",
-  "generatedAt": "2026-08-16T22:20:50.517Z",
+  "version": "0.1.18-rc.30",
+  "generatedAt": "2026-09-21T21:54:22.984Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/agent-meta/skills/basic-envelope/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: basic-envelope
-description: How to use @owlmeans/basic-envelope — Envelope data model for wrapping payloads with metadata for cryptographic signing/verification. Auto-invoked when importing envelope types or wrapping messages for signing.
+description: How to use @owlmeans/basic-envelope — makeEnvelopeModel for wrapping a payload with a type tag, timestamp and TTL, signing and verifying it with a basic-keys key pair, and serializing it as a wrap or a token. Auto-invoked when importing envelope types, or building a signed challenge or token payload.
 user-invocable: false
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
@@ -8,25 +8,78 @@ user-invocable: false
 # @owlmeans/basic-envelope
 
 **Layer:** Core
-**Install:** `"@owlmeans/basic-envelope": "^0.1.18-rc.0"` in `dependencies`
+**Install:** `"@owlmeans/basic-envelope": "^0.1.18-rc.30"` in `dependencies`
+
+An envelope is a signed, self-expiring container: a type tag, an encoded message, a timestamp and a
+TTL, plus the signature over all of it. It is what carries auth challenges and tokens between
+services, because a receiver can check the type, the age and the signature without knowing what the
+message means.
 
 ## Key Exports
 
 | Export | Description |
 |--------|-------------|
-| `Envelope` types | Wrapped payload shape (header, payload, signature) |
-| `EnvelopeModel` | Helpers to build/parse envelopes |
-| Constants | Envelope kinds, header field names |
+| `makeEnvelopeModel<T>(type, kind?)` | Build a new envelope, or parse an existing one |
+| `EnvelopeModel<T>` | `envelope` / `send` / `message` / `type` / `wrap` / `tokenize` / `sign` / `verify` |
+| `EnvelopeModel.envelope` | The `Envelope` itself — read `dt`/`ttl` from it, e.g. to size a cache entry |
+| `Envelope` | The wire shape: `{ t, msg, sig?, dt, ttl }` |
+| `EnvelopeKind` | `Wrap` (base64) and `Token` (base64url, no padding) |
+| `DEFAULT_TTL` | 5 minutes, in milliseconds |
+
+## Creating, signing, sending
 
-## Usage
+Called with a type tag alone, `makeEnvelopeModel` starts a fresh envelope stamped with the current
+time and `DEFAULT_TTL`. `send()` sets the payload — a string is stored as is, anything else is
+JSON-encoded and base64'd — takes an optional TTL where `null` means never expires, and **returns
+the model**, so the chained form is the idiomatic one.
 
 ```typescript
-import { Envelope, EnvelopeModel } from '@owlmeans/basic-envelope'
+import { makeEnvelopeModel, EnvelopeKind } from '@owlmeans/basic-envelope'
+import { RELY_3RD, type RelyToken } from '@owlmeans/auth'
+import { fromPubKey, makeKeyPairModel } from '@owlmeans/basic-keys'
+
+const key = makeKeyPairModel(privateKey)
+
+// unsigned, serialized in one expression
+const plain = makeEnvelopeModel<RelyToken>(RELY_3RD).send(rely).tokenize()
 
-const envelope = EnvelopeModel.wrap({ kind: 'auth-token', payload: { entityId: 'abc' } })
-// signature is added by basic-keys
+// signed
+const envelope = makeEnvelopeModel<RelyToken>(RELY_3RD)
+envelope.send(rely)
+const token = await envelope.sign(key, EnvelopeKind.Token)
 ```
 
+`sign(key, kind?)` stores the signature on the envelope and returns it; pass `EnvelopeKind.Wrap` or
+`EnvelopeKind.Token` to get the whole serialized envelope back instead. `wrap()` and `tokenize()`
+serialize without signing — a token is URL-safe, a wrap is not.
+
+The type tag and the payload type are the caller's — the example borrows `RELY_3RD` and `RelyToken`
+from `@owlmeans/auth`, which this package does not depend on. Any string works as a tag.
+
+The envelope itself is public as `model.envelope`, which is how a caller reaches `dt` and `ttl` —
+a server that caches a received envelope for exactly as long as it is valid reads
+`envelope.envelope.ttl` and derives the entry's lifetime from it.
+
+## Parsing and verifying
+
+Pass the serialized string as the first argument together with the kind it was produced in:
+
+```typescript
+const received = makeEnvelopeModel<RelyToken>(token, EnvelopeKind.Token)
+
+if (received.type() !== RELY_3RD) { /* wrong kind of message */ }
+if (!await received.verify(fromPubKey(publicKey))) { /* forged or expired */ }
+
+const rely = received.message()               // decoded payload
+const raw = received.message(true)            // the encoded string, untouched
+```
+
+`verify` answers `false` — it does not throw — when the envelope carries no signature, when
+`dt + ttl` is already in the past, or when the signature does not match. The signature covers the
+envelope with `sig` removed, so re-serializing a verified envelope keeps it verifiable. `message()`
+falls back to returning the raw string when the payload was not JSON.
+
 ## Depends On
 
-- None at runtime — pure model
+- `@owlmeans/basic-keys` — the `KeyPairModel` that signs and verifies
+- `@scure/base`, `@noble/curves`, `@noble/hashes` — encoding and the underlying primitives

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/basic-envelope",
-  "version": "0.1.18-rc.3",
+  "version": "0.1.18-rc.30",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -9,9 +9,6 @@
     "watch": "tsc -b -w --preserveWatchOutput --pretty",
     "test": "bun test ./tests"
   },
-  "bin": {
-    "owlkeys": "./build/bin.js"
-  },
   "main": "build/index.js",
   "module": "build/index.js",
   "types": "build/index.d.ts",
@@ -26,15 +23,15 @@
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",
-    "@owlmeans/test-auth": "^0.1.18-rc.3",
-    "@types/bun": "^1.3.14",
+    "@owlmeans/test-auth": "^0.1.18-rc.30",
+    "@types/bun": "^1.4.0",
     "nodemon": "^3.1.14",
     "typescript": "^7.0.2"
   },
   "dependencies": {
     "@noble/curves": "^1.6.0",
     "@noble/hashes": "^1.5.0",
-    "@owlmeans/basic-keys": "^0.1.18-rc.3",
+    "@owlmeans/basic-keys": "^0.1.18-rc.32",
     "@scure/base": "^2.3.0"
   },
   "publishConfig": {