@a2a-exposed/encryption 0.0.0-stage → 0.8.56

package/DEPENDENCIES.md

@@ -0,0 +1,31 @@
+# Foundation dependency review
+
+Snapshot: 2026-11-12. The lockfile pins the complete resolved graph and registry
+integrity hashes. Direct runtime dependencies are hpke-js `@hpke/core` 1.10.1,
+`@hpke/dhkem-x25519` 1.8.1 and `@hpke/chacha20poly1305` 1.8.1. Their repository
+is https://github.com/dajiaji/hpke-js and declared license is MIT. Transitive
+`@hpke/common` is pinned in package-lock.json. No install scripts are needed.
+
+The published [nonce-reuse advisory](https://github.com/dajiaji/hpke-js/security/advisories/GHSA-73g8-5h73-26h4)
+affects core <=1.7.4 and is patched in 1.7.5; this package pins 1.10.1 and uses
+one fresh context and one Seal per encrypted copy. `npm audit` reported zero
+known advisories for this lockfile at review time. Neither a clean advisory
+scan nor successful vectors constitutes an independent cryptographic audit.
+No formal audit is asserted for this library or application construction.
+
+Tests include the public RFC 9180 X25519/HKDF-SHA256/ChaCha20Poly1305 base
+vector and local malformed/tampered input cases. Manual interop uses PyHPKE
+0.6.5 over cryptography 50.0.2 to verify the envelope signature, open each copy
+and check its commitment; these are test dependencies only, not package runtime
+dependencies. They do not prove complete transport/trust/history integration.
+
+Reproduce manual interop in an isolated Python environment with those versions:
+
+```sh
+node test/cross-language.mjs /private/new-disposable-fixture.json
+python test/cross-language.py /private/new-disposable-fixture.json
+```
+
+The generator refuses existing files and writes disposable keys mode 600,
+without printing them. Remove that generated fixture after the check; retain
+only its result/provenance and these reproducible scripts. Never use real keys.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Telegraphic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/LOCAL-CUSTODY-DRAFT.md

@@ -0,0 +1,263 @@
+# Local custody/trust API — implementation checkpoint
+
+The local-state and delivery-ledger APIs support custody, retained receiving-key
+rotation and local replay/outbox operations. CLI enrollment, encrypted transport
+and the complete CLI/stdio MCP flow remain pending. Privileged caller attestations
+require a reviewed host integration before enabling traffic.
+
+`stores()` lists explicit choices without creating credentials. `LocalState`
+opens an existing database read-only by default; `create:true` initializes a new
+owner-only encryption directory and database, while `write:true` is needed for
+existing-state actions. File keys use exclusive mode-600 writes in a 0700 folder.
+Status exposes only public bundles/store/provenance. `loadIdentity` is a privileged
+in-process API, not tool output; it self-checks private/public correspondence
+without network and refuses live traffic use. Lost files never trigger rotation.
+
+The optional pinned `@napi-rs/keyring` 2.1.2 adapter is isolated in a bounded child
+process; secrets use stdin/stdout pipes inside the local process, not command
+arguments, environment variables or transcript output. Linux explicitly selects
+Secret Service, never the reboot-volatile kernel fallback. No OS credential entry
+is accessed unless `allowOsConsent:true` is explicitly supplied by the owner-facing
+caller. Native operations may need the owner's OS authorization; file storage is
+the unattended alternative. There is no silent fallback. Native-provider errors
+are fixed local codes; a timed-out operation may require status/recovery review,
+not an assertion that a key was deleted. Windows file protection uses an explicit
+current-user ACL and fails if it cannot establish/check it. Native platform
+operations and Windows ACL behavior have not been exercised on real accounts.
+
+Trust proposals bind config/local identities and key bundle, exact endpoint,
+pairing identity, full old record/version, new bundle/policy/verification decision,
+operation and nonce. Approving uses exact compare-and-swap; older approvals fail.
+Prior approved records are retained separately for future archive opening.
+New/pending proposals hold the live state, and losing a key does not change pins.
+`tofu-pinned` is local trust, not evidence a remote token pairing exists; pairing
+is explicitly not checked by this API. Independent verification requires the
+owner's separate-channel decision. The safety code is computed locally.
+
+The `ownerApproved`, `independentVerified` and `rePairVerified` arguments are
+privileged caller attestations, not proofs. A CLI/MCP integration must obtain
+human approval of the exact proposal and a separately verified pairing outcome;
+it must never populate these flags from peer messages, hosted assertions or
+untrusted API input. No network route exposes these methods. This checkpoint
+is not approval to use that incomplete integration with real credentials.
+
+Current tests use disposable private directories and synthetic in-memory keys.
+They cover restart/own-copy opening, read-only discovery, no private keys in
+status/SQLite, file modes/symlinks/loss, explicit stores/consent, exact approval,
+independent/re-pair holds, concurrent proposals and retained trust history.
+No native keychain entries, server credentials, pairing grants or live resources
+were touched. Public protocol/privacy acceptance remains a later gate.
+
+Initialization commits a public recovery intent before the first external write.
+An uncertain outcome blocks new initialization until an explicit exact-digest
+reconciliation; an absent observation retains the old intent for late completion.
+Adoption self-checks the original credential and never replaces an active identity.
+The native broker PID is committed before private pipe input, and reconciliation
+refuses a still-running broker. Timeout handling waits for exit/close, escalates
+termination, and reports an unreaped process as unknown rather than success.
+
+Safety-code inspection accepts the exact pending proposal digest before approval;
+without it a pending change refuses to show the old code. Independent approval
+also binds the compared proposal digest. Identity replacement requires both
+separately approved re-pairing and independent re-verification. Literal boolean
+OS consent is checked at both custody and broker boundaries. Schema version,
+structure and integrity are checked without migration or replacement. Public
+status/proposal/history listings have explicit bounded continuation inputs.
+
+The isolated backup byte-format primitive uses bounded scrypt and authenticated
+AES-GCM. The local store snapshot API described below uses it; it never enables restored
+live keys. Cross-process tests cover racing initialization and process death after a
+mock credential write; native lifecycle tests use simulated child processes only.
+
+Recovery approval is action-specific. Each operation listing includes a monotonic
+revision and `recovery_choices` with the approval digest for adopt or
+abandon-if-absent. Pass the exact listed `approvalDigest` alongside the immutable
+operation digest and explicit human approval. The digest binds configuration,
+operation, state, revision and action; it is invalid after any transition, even
+when the state name is unchanged. After provider reads and key self-checks, the
+final SQLite transaction compares the original state/revision/digest before
+changing it. A stale adoption rolls back any identity insertion. List and obtain
+a new approval rather than reusing an earlier one. The unreleased schema is
+version 6; earlier draft stores are preserved and refused, never auto-migrated.
+
+
+## Protected backup and archive-only restore API
+
+`state.createBackup({destination,passphrase,allowOsConsent})` takes a separate
+consistent SQLite read transaction, validates bounded static-table rows and all
+private/public key pairs, encrypts them, then writes a new exclusive protected
+file. Passphrase is an in-process Uint8Array from a protected source, never a
+command argument or tool-visible field. Credentials stay out of public output.
+Known lost keys and unresolved credential writes refuse backup. An explicitly
+observed-absent credential remains catalogued and counted as absent; the backup
+cannot recover a credential written after that observation/snapshot.
+
+`restoreBackup({source,destination,passphrase,store:"file",
+acknowledgeReplayRollback:true})` requires a new destination, explicit file-store
+selection and replay-rollback acknowledgment. Native restores are unsupported;
+there is no silent store fallback. Validate every decrypted row and available
+key before creating a target directory. Import uses a private staging directory
+with a durably recorded archive-only hold before private writes, then atomically
+installs the canonical encryption directory. A failed/interrupted stage remains
+protected for inspection; never overwrite it on retry. Existing targets are
+never merged. The encrypted source backup remains the recovery source.
+
+The restored config gets a fresh config UUID and records its source UUID and
+public operation provenance hash. Private keys, historical pins, proposals,
+replay rows and pending delivery IDs are retained; original provider credentials
+are converted to explicitly selected protected files. The global restore hold
+blocks key initialization, recovery actions and trust writes; identity rows and
+inspection show archive-only, and live-use loads remain refused. No automatic
+resend or delivery happens. A future separate fresh receiving identity and peer
+re-verification flow is required before live enrollment; it is not implemented.
+This is a local API checkpoint, with no working backup/restore CLI command yet.
+
+## Local receiving-key rotation
+
+`rotationPlan(id)` lists the exact current key/store and an action-specific
+approval digest bound to config, previous bundle and latest operation revision.
+`rotateLocal({id,approvalDigest,ownerApproved:true,allowOsConsent})` retains the
+Ed25519 identity and old X25519 keys, generates a fresh receiving key, and follows
+the same durable intent/write/commit/reconciliation rules as initialization.
+Concurrent plans produce only one successor. A failed write never retires the
+old current key; uncertain writes hold further rotation until exact recovery.
+Retired rows cannot authorize new trust proposals/approvals or safety-code claims.
+Existing peer bindings stay held after rotation until a new independently
+verified local-key proposal is approved; rotation grants no remote pairing.
+Backups include both old and new private keys, and restores retain them under
+the archive-only hold. There is no key deletion API or live key advertisement.
+
+Backup preflight checks the passphrase and destination existence before any
+credential read; a racing exclusive-create failure is backup_destination_exists.
+Restore syncs the SQLite file and staging directory, then the promoted directory
+and its parents where directory fsync is supported. Results distinguish
+file-and-directory-sync-completed from directory-sync-unverified. These record
+completed system calls, not proof of hardware power-loss durability. Unsupported
+platform directory sync remains unverified. A sync/I/O failure after promotion
+returns restore_installed_readback_failed and retains the archive-only target;
+it must not suggest an automatic overwrite/retry. Native/Windows durability and
+real power-loss behavior are untested.
+
+## Durable initial-request receiver API
+
+The unreleased local-state schema is version 6 for SDK host-grant staging,
+assignment/provenance and outbound/chain tables; earlier drafts remain preserved/refused, not migrated.
+`DeliveryLedger` is a privileged local API with no HTTP/model callback. Its
+pairingVerified/pairingIdentity/activation arguments are trusted local-transport
+attestations, never peer-controlled fields or permission grants. The real client
+adapter must derive them from existing human-authorized pairing and negotiated
+transport; that adapter/traffic path is not implemented here.
+
+`receiveInitial` verifies public signature/bindings before credential access,
+opens the request and prepares its signed assignment, then rechecks the exact
+current pin and atomically commits replay, assignment, ciphertext delivery and
+provenance. No computed receipt escapes a failed commit. Namespace uses the
+stable local signing identity plus peer identity/message ID, surviving X25519
+rotation. Exact duplicates reuse the original receipt/ackId/deliveryId; changed
+context/digest/task or conflicting task assignment refuses. A stable local/peer/task ID binds exactly one initial request/context, enforced both by a transaction check and database uniqueness across contexts. New pending trust or
+revocation during verification prevents commit. SQLite contains ciphertext and
+public provenance, not opened content.
+
+Pending receipt publication and model consumption are distinct. Cached receipt
+preparation requires current pairing/trust and never re-signs a new assignment.
+Transport acceptance does not claim peer receipt. Delivery reads are explicit,
+untrusted and at-least-once with a stable ID; only explicit consumed acknowledgment
+closes the local outbox. No exactly-once external-effect guarantee is made.
+Revoked/pending/rotated trust holds live reads and publication, while historical
+rows remain. Restored archive-only state lists those rows but cannot create,
+consume or acknowledge live work. Backups retain new ledger rows as encrypted
+archive state; full semantic/interop restore audit is still an acceptance gate.
+## Local sender, response and chain API
+
+These methods remain isolated SDK algorithms; no CLI/Worker transport is enabled.
+`prepareRequest` commits a self-opened encrypted request before returning its ID;
+`beginTransmission` commits transmitting before releasing the cached ciphertext
+once. A crash or timeout leaves unknown delivery, never permission for automatic
+re-send/new-ID/plaintext fallback. `recordTransport` retains provisional transport
+IDs separately; only a verified immutable peer assignment grants task authority.
+`acceptAssignment` pins that assignment and can hold a co-carried later snapshot
+while complete signed history is obtained; `acceptResponse` requires a previously
+pinned assignment and an inner digest of the exact locally prepared request.
+Acceptance and readback share an answered-request validator: the cached row must
+have user-request provenance (null reference_digest), an attempted state, exact
+current trust/key and digest, and a cached role=user/kind=message envelope whose
+IDs and sender/recipient match. An outgoing agent response is never a request
+being answered, even when both task directions share context/task strings.
+The local adapter must validate actual Task wrappers before attesting their IDs.
+
+`receiveFollowup` requires the existing inbound assignment, exact context/task and
+protocol. It queues ciphertext/provenance/replay atomically; duplicate packets keep
+the same local delivery ID. `prepareResponse` binds the exact accepted request
+and commits its ciphertext before transmission. Full snapshots start at revision
+zero, then bind the previous signed envelope digest. Snapshot head and outgoing
+ciphertext share a transaction, and concurrent creators compare the original
+head. Accepted snapshots must be consecutive; gaps refuse as provenance_incomplete,
+forks/terminal resurrection refuse, and older accepted snapshots read history-only.
+Terminal heads reject new follow-ups. These checks do not establish real adapter,
+Task-history ordering, multi-process sender, semantic restore or live traffic
+acceptance; those remain separate gates.
+
+
+## Local Task reconstruction
+
+`acceptTask` accepts an exact raw Task for an explicitly selected cached initial
+request. It validates any receipt and all public signatures before loading keys,
+opens agent events, and orders snapshots by commitment-checked revisions.
+One transaction binds the immutable assignment and queues the entire verified
+batch with replay/provenance/chain state. An incomplete or forked chain, changed
+trust or failed commit leaves no partial new assignment/delivery/head. Cached
+history user messages must be actual attempted local user requests; response-to-
+response correlation remains refused. Omitted Task artifacts are empty; present
+artifacts must still be an empty array. Routing-only cancellation cannot replace
+currentPeerState, which is derived from signed local chain state. The result
+returns IDs, not plaintext or model consumption. No actual network adapter calls
+this isolated API yet; archive/native/traffic/release gates remain.
+
+
+Task import does not place ordinary agent messages on the snapshot chain. A new
+unsequenced message is held with task_terminal if the known head or incoming
+verified batch is terminal, regardless of server array order or poll grouping.
+The whole rejected batch rolls back, including any new assignment. Previously
+accepted duplicate IDs remain stable; this does not infer their chronology from
+sentAt. Terminal content belongs inside a signed full snapshot. Separate archive
+opening remains unavailable and cannot authorize live delivery.
+
+A locally retained, exact current-pin assignment remains valid for fresh
+follow-ups after the initial envelope's 30-day admission window. The closed
+retained-cache path checks request bytes/digest/purpose/provenance and both request
+and receipt signatures against current bundles; a repeated receipt must equal
+the immutable saved one. It does not backdate now or expose an archive-mode flag.
+First unassigned requests/receipts still use live admission freshness, and every
+incoming agent envelope still passes the current-time live freshness checks.
+
+
+Transport proposals may include the exact peerEndpoint independently of the key
+bundle cardUrl, on the same canonical HTTPS origin. This endpoint is part of the
+human-approved proposal/record digest; a discovered interface cannot silently
+replace it. Bundle input is synchronously cloned before asynchronous verification.
+Existing omitted-endpoint SDK calls keep cardUrl as their endpoint and require a
+new explicit proposal before using another protocol path.
+
+
+LocalState.locked may take a trusted authorizationGuard plus withAuthorizationLease.
+Both must be functions and must be provided together. The host lease precedes the
+DB queue, encloses the complete transaction, and must coordinate every actual
+pairing-store writer. The synchronous guard returns literal true before writes
+and after the action await immediately before COMMIT; failure rolls back. The
+Task transport supplies this guard from its fresh local pairing reader, including
+effective credential and endpoint, rather than reusing a captured verified flag.
+No actual cross-process pairing store or public approval proof is added here.
+
+The host pairing snapshot includes a nonnegative safe-integer revision. Every
+revocation, restoration or credential-generation change increments it under the
+same host lease, even if token bytes later match again. Final guard comparison
+includes this revision to reject in-flight revoke/restore ABA changes. The real
+store must persist/enforce that monotonicity; a synthetic reader does not prove it.
+
+
+Schema 6 host-grant rows are internal coordination metadata, not admission. Older
+draft databases are preserved/refused without migration. Nonempty host-grant
+history (including void records) currently refuses backup/restore before private
+credential access or output/destination creation; nothing is silently omitted.
+Empty-host custody snapshots retain archive-only restore. Full host-grant archive
+semantics and live coordinator integration need separate review.

package/README.md

@@ -1,3 +1,136 @@
-# Temporary Holding Version
+# @a2a-exposed/encryption
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Local primitives and key custody for the [sealed A2A extension](../docs/extensions/sealed-v1.md).
+The optional CLI and stdio MCP integration uses this package for local encryption
+and decryption. Install the matching version in the selected config directory;
+see [local keys and pairing](../docs/local-key-pairing.md). Installation does not
+enable traffic: exact `A2A_SEALED_ENABLED=1` requires owner approval separately in
+each local process and inbox Worker. No cryptographic audit is claimed.
+
+The package uses pinned hpke-js RFC 9180 primitives and Ed25519 signatures.
+It seals independently to the recipient and sender-history keys and binds both
+copies with a salted commitment. Keys stay in the caller's local process.
+`generateIdentity`, `verifyBundle`, `seal`, `open`, `canonicalJSON` and `parseJSON`
+are the draft API. Callers must provide exact outer bindings and locally pinned
+public bundles, and persist policy/replay records before delivering plaintext.
+`seal` self-opens the sender archive copy before returning. `open` is a primitive,
+not authorization or replay storage: it does not validate the integration
+message/snapshot union or content/header semantics, so it must not deliver to a
+model directly. Object-form `open` cannot recover duplicate JSON names lost by
+an upstream parser; validate bounded raw transport JSON before using that form.
+The top-level primitive does not implement archive/history, durable delivery or
+trust authorization. Invalid caller-supplied clock values are refused.
+
+Static keys do not provide forward secrecy. Lost keys can make old history
+unreadable. Host operators still observe routing, timing, state and size. Once
+opened, content is visible to the local agent/model provider.
+
+Run `npm ci --ignore-scripts` and `npm test` in this directory. Pack with
+`npm pack --dry-run`; no release or deployment is performed. Node 22.18+.
+
+The separate `./local-state` API is an incomplete local custody/trust checkpoint.
+See [local custody contracts](LOCAL-CUSTODY-DRAFT.md) for protected local backup
+and archive-only restore APIs. Local receiving-key rotation retains old keys under exact explicit approval.
+The opt-in CLI uses local custody and pins; privileged local replay/outbox APIs below are separate from that integration.
+
+
+`./content` validates the exact supported plaintext union and losslessly maps
+supported inline parts between A2A 0.3/1.0 without fetching file URIs.
+`./carriers` checks structural message carriers/bindings only. See packaged
+`schemas/` and the [SDK integration contract](../docs/extensions/sealed-v1-sdk.md).
+Neither API replaces signatures, local
+trust, assignment, replay/chain checks or model-delivery authorization. The CLI
+message path uses them without implementing the separate ledger/assignment APIs below.
+
+
+`./assignment` verifies request/response correlation and signed task assignment
+primitives. Receipt-bearing codecs preserve the control receipt separately from
+ciphertext. They do not establish durable acceptance/model consumption;
+use the local ledger and reviewed host authorization before publication/delivery.
+
+
+`./ledger` adds local durable initial-request acceptance: cached assignment,
+replay and ciphertext outbox commit together before a receipt is returned.
+Delivery/publication reads and acknowledgments are separate local operations;
+there is no network/model callback. Pairing/activation are trusted caller
+attestations until a reviewed transport adapter exists. Local outbound preparation,
+one-time transmission authorization, correlated response acceptance, follow-ups
+and consecutive snapshot chains are implemented without network callbacks.
+See [the local sender contract](LOCAL-CUSTODY-DRAFT.md#local-sender-response-and-chain-api).
+Actual messaging, semantic restore and real platform acceptance
+remain gated.
+
+
+`./tasks` extracts exact raw 0.3/1.0 Task wrappers and history without ordinary
+normalizers. It preserves sealed events and assignment controls, rejects outer
+plaintext/artifacts and conflicting bindings, and marks routing state and history
+order unverified. This parser does not authenticate receipts, reconstruct chains
+or deliver content; the privileged ledger and future transport adapter must do so.
+
+
+`DeliveryLedger.acceptTask` connects this extraction to the local cryptographic
+and transaction gates: verify receipts/signatures, open content, order snapshots
+by verified revisions, then commit the whole assignment/delivery/chain batch.
+It returns stable delivery IDs and verified chain state separately from untrusted
+routing state. Gaps/forks/failure do not partially publish new work. It remains a
+privileged local API; no Worker/CLI/MCP messaging route enables it yet.
+
+
+`./transport` provides a privileged sealed-only JSON-RPC client for explicit local
+hosts. It takes a fresh local pairing/credential callback, approved endpoint,
+fixed protocol and a card matching the approved bundle. Send releases a prepared
+ciphertext once; polling uses a locally signed assignment. Activation echo is
+required on every response, redirects are refused, and failures never trigger a
+new ID, version or plaintext retry. Results contain IDs/state and truthful send
+privacy facts, not plaintext or credentials. Tests use synthetic fetch/provider
+fixtures. This privileged transport export is separate from the opt-in CLI/Worker integration; it enables no traffic automatically.
+
+
+Transport hosts must provide withPairingLease(run) as well as the fresh pairing
+reader. The host coordinates all pairing/credential writers; guarded acceptance
+rechecks authorization before writes and COMMIT. Unsupported tenant routing and
+contradictory legacy interfaces are refused. Concurrent send failures inspect the
+current original-ID state and never label another caller's attempt not-sent.
+The real CLI pairing-store lock remains unimplemented and is not validated by
+synthetic no-op lease fixtures.
+
+The host pairing snapshot includes a nonnegative safe-integer revision. Every
+revocation, restoration or credential-generation change increments it under the
+same host lease, even if token bytes later match again. Final guard comparison
+includes this revision to reject in-flight revoke/restore ABA changes. The real
+store must persist/enforce that monotonicity; a synthetic reader does not prove it.
+
+
+The internal maintenance queue retains in-process SDK ordering across separate
+SQLite commits and stages immutable host-grant metadata. It does not supply a
+cross-process authority lock or make ready records eligible for live traffic.
+Schema 6 refuses older draft stores without migration; nonempty host-grant
+history currently blocks backup/restore. See the [maintenance contract](../docs/extensions/sealed-v1-sdk.md#internal-maintenance-and-staged-grant-records).
+
+The disabled continuation storage foundation also has private historical signer-plan
+metadata diagnosis. It authenticates each plan at its original creation time and
+preserves its original epoch, revision and signer identity after planning state
+changes. Freshness in that inventory describes time only; it does not select a
+current signer or make a plan applicable. Normal plan reads still require the
+current authority binding and an unexpired plan. No physical nonempty authority
+reader, enrollment application or command uses this historical inventory yet.
+The private `diagnoseBindings` inventory also compares every original plan to a
+strictly snapshotted caller binding. `bindingMatches` and time freshness are
+independent metadata; equality does not authenticate that caller as the current
+authority, prove approval or make a plan applicable.
+The private `readRetained` lookup preserves exact original planning bytes for
+future uncertainty reconciliation, including expired plans. It authenticates
+only the explicitly selected ID and returns deeply frozen private data, never
+diagnostic output or an applicable plan. Fresh reads keep their original gates;
+no physical authority reader, command or enrollment writer calls this lookup.
+
+The private physical `diagnoseRetainedInitialContinuationSignerPlans` reader
+anchors historical plan comparison to the initial suspended schema-4 authority.
+It retains authenticated nonmatching originals as metadata and keeps time status
+independent of `bindingMatches`. Corruption refuses the whole inventory; signer
+history and advanced physical authority still refuse. No enrollment or traffic
+path uses this diagnostic.
+
+`local-state.localSafetyCode` computes the deterministic public-bundle comparison
+code used by local CLI pairing. Computing or displaying it grants no approval;
+initial human-approved pairing pins remain TOFU until a separate verification.

package/assignment.mjs

@@ -0,0 +1,68 @@
+// Signed assignment primitives. Publication requires the later atomic replay/outbox transaction.
+import {randomUUID}from'node:crypto';
+import {canonicalJSON,parseJSON,validateEnvelopeStructure,validatePeerStructure,verifyBundle,open,EncryptionError}from'./index.mjs';
+import {validateContent}from'./content.mjs';
+const fail=code=>{throw new EncryptionError(code||'assignment_invalid');};
+const encoder=new TextEncoder();
+const peer=bundle=>({cardUrl:bundle.cardUrl,identityKey:bundle.identityKey,keyId:bundle.keyId});
+const exact=(value,keys)=>value&&typeof value==='object'&&!Array.isArray(value)&&Object.keys(value).sort().join('\0')===[...keys].sort().join('\0');
+const id=value=>typeof value==='string'&&/^[\x21-\x7e]{1,200}$/.test(value);
+function raw(value,size){if(typeof value!=='string'||!/^[A-Za-z0-9_-]+$/.test(value))fail();const bytes=Buffer.from(value,'base64url');if(bytes.length!==size||bytes.toString('base64url')!==value)fail();return bytes;}
+const digest=async value=>Buffer.from(await crypto.subtle.digest('SHA-256',encoder.encode(canonicalJSON(value)))).toString('base64url');
+const binding=header=>Object.fromEntries(['contextId','messageId','taskId','role','state','kind'].map(key=>[key,header[key]]));
+const same=(left,right)=>canonicalJSON(left)===canonicalJSON(right);
+const snapshotBundle=value=>parseJSON(canonicalJSON(value));
+function snapshotIdentity(value){if(!value||typeof value!=='object')fail();return {bundle:snapshotBundle(value.bundle),signingKey:value.signingKey,encryptionKey:value.encryptionKey};}
+function time(now){if(!Number.isSafeInteger(now)||now<0||now>8640000000000000)fail();}
+export function validateAssignmentStructure(value){
+ const receipt=typeof value==='string'?parseJSON(value):parseJSON(canonicalJSON(value));
+ if(!exact(receipt,['v','kind','requestDigest','from','to','contextId','requestMessageId','taskId','responseKind','responseDigest','ackId','signature'])||receipt.v!==1||receipt.kind!=='assignment'||receipt.responseKind!=='task'||!id(receipt.contextId)||!id(receipt.requestMessageId)||!id(receipt.taskId)||typeof receipt.ackId!=='string'||!(/^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/).test(receipt.ackId))fail();
+ validatePeerStructure(receipt.from);validatePeerStructure(receipt.to);raw(receipt.requestDigest,32);if(receipt.responseDigest!==null)raw(receipt.responseDigest,32);raw(receipt.signature,64);return receipt;
+}
+export async function envelopeDigest(envelope){return digest(validateEnvelopeStructure(envelope));}
+async function validateContext({requestEnvelope,senderBundle,recipientBundle,now,purpose}){
+ time(now);if(!['live','archive'].includes(purpose))fail();const request=validateEnvelopeStructure(requestEnvelope),h=request.header;
+ if(h.taskId!==null||h.role!=='user'||h.kind!=='message'||h.state!==null||!same(h.from,peer(senderBundle))||!same(h.to,peer(recipientBundle)))fail();
+ if(purpose==='live'&&(Date.parse(h.sentAt)<now-30*86400000||Date.parse(h.sentAt)>now+300000))fail('replay');
+ await verifyBundle(senderBundle,{cardUrl:senderBundle.cardUrl,identityKey:senderBundle.identityKey,now});await verifyBundle(recipientBundle,{cardUrl:recipientBundle.cardUrl,identityKey:recipientBundle.identityKey,now});return request;
+}
+export async function verifyAssignment({receipt:input,requestEnvelope,senderBundle,recipientBundle,responseEnvelope=null,expectedTaskId,now=Date.now(),purpose='live'}={}){
+ try{
+  requestEnvelope=validateEnvelopeStructure(requestEnvelope);senderBundle=snapshotBundle(senderBundle);recipientBundle=snapshotBundle(recipientBundle);responseEnvelope=responseEnvelope===null?null:validateEnvelopeStructure(responseEnvelope);
+  const receipt=validateAssignmentStructure(input),request=await validateContext({requestEnvelope,senderBundle,recipientBundle,now,purpose}),h=request.header;
+  if(!same(receipt.from,peer(recipientBundle))||!same(receipt.to,peer(senderBundle))||receipt.contextId!==h.contextId||receipt.requestMessageId!==h.messageId||receipt.requestDigest!==await envelopeDigest(request)||(expectedTaskId!==undefined&&receipt.taskId!==expectedTaskId))fail('assignment_binding_mismatch');
+  const {signature,...body}=receipt;const key=await crypto.subtle.importKey('raw',raw(recipientBundle.identityKey,32),'Ed25519',false,['verify']);
+  if(!await crypto.subtle.verify('Ed25519',key,raw(signature,64),encoder.encode('a2a-exposed sealed assignment v1\n'+canonicalJSON(body))))fail();
+  if(responseEnvelope===null){if(receipt.responseDigest!==null)fail('response_binding_required');}
+  else{
+   const response=validateEnvelopeStructure(responseEnvelope),r=response.header;
+   if(receipt.responseDigest===null||receipt.responseDigest!==await envelopeDigest(response)||!same(r.from,peer(recipientBundle))||!same(r.to,peer(senderBundle))||r.contextId!==h.contextId||r.taskId!==receipt.taskId||r.role!=='agent')fail('response_binding_mismatch');
+  }
+  return receipt;
+ }catch(error){if(error instanceof EncryptionError)throw error;fail();}
+}
+export async function createAssignment({identity,senderBundle,requestEnvelope,taskId,responseEnvelope=null,ackId=randomUUID(),now=Date.now()}={}){
+ try{
+  identity=snapshotIdentity(identity);senderBundle=snapshotBundle(senderBundle);requestEnvelope=validateEnvelopeStructure(requestEnvelope);responseEnvelope=responseEnvelope===null?null:validateEnvelopeStructure(responseEnvelope);
+  const request=await validateContext({requestEnvelope,senderBundle,recipientBundle:identity.bundle,now,purpose:'live'});
+  const requestContent=validateContent(await open({envelope:request,identity,sender:senderBundle,recipient:identity.bundle,expected:binding(request.header),now}),request.header);
+  if(!id(taskId))fail();const requestDigest=await envelopeDigest(request);
+  if(responseEnvelope!==null){
+   const response=validateEnvelopeStructure(responseEnvelope),h=response.header;
+   if(h.contextId!==request.header.contextId||h.taskId!==taskId||h.role!=='agent')fail();
+   validateContent(await open({envelope:response,identity,sender:identity.bundle,recipient:senderBundle,expected:binding(h),purpose:'sender',now}),h,{expectedRequestDigest:requestDigest});
+  }
+  const body={v:1,kind:'assignment',requestDigest,from:peer(identity.bundle),to:peer(senderBundle),contextId:request.header.contextId,requestMessageId:request.header.messageId,taskId,responseKind:'task',responseDigest:responseEnvelope===null?null:await envelopeDigest(responseEnvelope),ackId};
+  const receipt={...body,signature:Buffer.from(await crypto.subtle.sign('Ed25519',identity.signingKey,encoder.encode('a2a-exposed sealed assignment v1\n'+canonicalJSON(body)))).toString('base64url')};
+  await verifyAssignment({receipt,requestEnvelope:request,senderBundle,recipientBundle:identity.bundle,responseEnvelope,expectedTaskId:taskId,now});
+  return {receipt,requestContent,untrusted:true}; // No durable acceptance/model-consumption claim.
+ }catch(error){if(error instanceof EncryptionError)throw error;fail();}
+}
+export async function openAssignedResponse({receipt,requestEnvelope,responseEnvelope,identity,recipientBundle,now=Date.now()}={}){
+ try{
+  receipt=validateAssignmentStructure(receipt);requestEnvelope=validateEnvelopeStructure(requestEnvelope);responseEnvelope=validateEnvelopeStructure(responseEnvelope);identity=snapshotIdentity(identity);recipientBundle=snapshotBundle(recipientBundle);
+  const verified=await verifyAssignment({receipt,requestEnvelope,senderBundle:identity.bundle,recipientBundle,responseEnvelope,now});
+  const response=validateEnvelopeStructure(responseEnvelope),content=validateContent(await open({envelope:response,identity,sender:recipientBundle,recipient:identity.bundle,expected:binding(response.header),now}),response.header,{expectedRequestDigest:verified.requestDigest});
+  return {receipt:verified,content,untrusted:true}; // Ledger/trust approval remains outside this primitive.
+ }catch(error){if(error instanceof EncryptionError)throw error;fail();}
+}

package/backup.mjs

@@ -0,0 +1,63 @@
+// Local encrypted-backup byte format. This module does not import or restore live state.
+import { randomBytes, scryptSync, createCipheriv, createDecipheriv } from "node:crypto";
+import { canonicalJSON, parseJSON } from "./index.mjs";
+export const MAX_BACKUP_FILE = 32 * 1024 * 1024;
+export const MAX_BACKUP_PLAINTEXT = 16 * 1024 * 1024;
+export class BackupError extends Error {
+ constructor(code) { super(code); this.code = code; }
+}
+const fail = (code = "backup_unreadable") => { throw new BackupError(code); };
+function passphraseBytes(input) {
+ if (!(input instanceof Uint8Array) || input.length > 4098) fail("passphrase_input");
+ let value = Buffer.from(input);
+ try { new TextDecoder("utf-8", { fatal: true }).decode(value); } catch { value.fill(0); fail("passphrase_input"); }
+ if (value.at(-1) === 10) { const end = value.at(-2) === 13 ? value.length - 2 : value.length - 1; value = value.subarray(0, end); }
+ if (value.length < 12) { value.fill(0); fail("passphrase_input"); }
+ return value;
+}
+export function validateBackupPassphrase(input) { const value = passphraseBytes(input); value.fill(0); return true; }
+const b64 = value => Buffer.from(value).toString("base64url");
+function raw(value, size, max) {
+ if (typeof value !== "string" || value.length > Math.ceil((size || max) * 4 / 3) || !/^[A-Za-z0-9_-]+$/.test(value)) fail();
+ const bytes = Buffer.from(value, "base64url");
+ if (b64(bytes) !== value || (size && bytes.length !== size) || (max && bytes.length > max)) fail();
+ return bytes;
+}
+function keyFor(passphrase, salt) { return scryptSync(passphrase, salt, 32, { N: 32768, r: 8, p: 1, maxmem: 64 * 1024 * 1024 }); }
+export function sealBackup(snapshot, passphrase) {
+ let password, key, plaintext;
+ try {
+  plaintext = Buffer.from(canonicalJSON(snapshot));
+  if (plaintext.length > MAX_BACKUP_PLAINTEXT) fail("backup_too_large");
+  password = passphraseBytes(passphrase);
+  const salt = randomBytes(32), nonce = randomBytes(12);
+  const header = { format: "a2a-exposed local backup", v: 1, kdf: "scrypt", N: 32768, r: 8, p: 1, salt: b64(salt), nonce: b64(nonce) };
+  key = keyFor(password, salt);
+  const cipher = createCipheriv("aes-256-gcm", key, nonce); cipher.setAAD(Buffer.from(canonicalJSON(header)));
+  const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final(), cipher.getAuthTag()]); plaintext.fill(0);
+  const text = canonicalJSON({ ...header, ct: b64(ciphertext) });
+  if (Buffer.byteLength(text) > MAX_BACKUP_FILE) fail("backup_too_large");
+  return text + "\n";
+ } catch (error) { if (error instanceof BackupError) throw error; fail(); }
+ finally { password?.fill(0); key?.fill(0); plaintext?.fill(0); }
+}
+export function openBackup(text, passphrase) {
+ let password, key, plaintext;
+ try {
+  if (typeof text !== "string" || Buffer.byteLength(text) > MAX_BACKUP_FILE) fail("backup_too_large");
+  const envelope = parseJSON(text, MAX_BACKUP_FILE);
+  if (!envelope || typeof envelope !== "object" || Object.keys(envelope).sort().join() !== ["format","v","kdf","N","r","p","salt","nonce","ct"].sort().join()) fail();
+  if (envelope.format !== "a2a-exposed local backup" || envelope.v !== 1 || envelope.kdf !== "scrypt" || envelope.N !== 32768 || envelope.r !== 8 || envelope.p !== 1) fail();
+  const salt = raw(envelope.salt, 32), nonce = raw(envelope.nonce, 12), ct = raw(envelope.ct, 0, MAX_BACKUP_PLAINTEXT + 16);
+  if (ct.length < 16) fail();
+  const { ct: ignored, ...header } = envelope;
+  password = passphraseBytes(passphrase); key = keyFor(password, salt);
+  const decipher = createDecipheriv("aes-256-gcm", key, nonce); decipher.setAAD(Buffer.from(canonicalJSON(header))); decipher.setAuthTag(ct.subarray(-16));
+  plaintext = Buffer.concat([decipher.update(ct.subarray(0, -16)), decipher.final()]);
+  if (plaintext.length > MAX_BACKUP_PLAINTEXT) fail("backup_too_large");
+  const value = parseJSON(new TextDecoder("utf-8", { fatal: true }).decode(plaintext), MAX_BACKUP_PLAINTEXT);
+  if (canonicalJSON(value) !== plaintext.toString("utf8")) fail();
+  return value;
+ } catch (error) { if (error instanceof BackupError) throw error; fail(); }
+ finally { password?.fill(0); key?.fill(0); plaintext?.fill(0); }
+}