skills/docs/networking/drive/drive-sharing/README.md

@suaveplan/drive-sharing - Partitioned drive sharing engine for the Suaveplan ecosystem: envelope encryption with mandatory AAD, per-user key wrapping, partition policies with deterministic action validation, revocable share tokens, expiring grants, and atomic cross-partition file transfer with rollback.

Summary

Partitioned drive sharing engine for the Suaveplan ecosystem. Ships envelope encryption with mandatory AAD, per-user key wrapping, partition policies with deterministic action validation, revocable share tokens, expiring grants, and atomic cross-partition file transfer with rollback. Every public boundary is Zod-validated, OTel-instrumented, and event-bus-aware.

Documentation tree

• envelope — (no submodules)
  • envelope — (no submodules)
• key-ring — (no submodules)
  • key-ring — (no submodules)
• error-codes — The error-codes module is the single source of truth for every failure category emitted by @suaveplan/drive-sharing…
  • error-codes — The error-codes module is the single source of truth for every failure category emitted by @suaveplan/drive-sharing…
• otel — (no submodules)
  • instruments — (no submodules)
• partition-manager — (no submodules)
  • partition-manager — (no submodules)
• partition-policy — (no submodules)
  • partition-policy — (no submodules)
• partition-store — (no submodules)
  • partition-store — (no submodules)
• grants — (no submodules)
  • grants — (no submodules)
• tokens — (no submodules)
  • tokens — (no submodules)
• transfer — (no submodules)
  • transfer — (no submodules)
• common — This module declares the foundational types shared by every other module in @suaveplan/drive-sharing. It owns the bra…
• schemas — This module declares Zod schemas for every public option type accepted by @suaveplan/drive-sharing. Schemas are wired…

- [envelope](./src/encryption/envelope/envelope.md) — _(no submodules)_- [key-ring](./src/encryption/key-ring/key-ring.md) — _(no submodules)_- [key-ring](./src/encryption/key-ring/key-ring.md) — _(no submodules)_- [otel](./src/otel/instruments.md) — _(no submodules)_- [instruments](./src/otel/instruments.md) — _(no submodules)_- [partition-manager](./src/partitions/partition-manager/partition-manager.md) — _(no submodules)_- [partition-manager](./src/partitions/partition-manager/partition-manager.md) — _(no submodules)_- [partition-policy](./src/partitions/partition-policy/partition-policy.md) — _(no submodules)_- [partition-policy](./src/partitions/partition-policy/partition-policy.md) — _(no submodules)_- [partition-store](./src/partitions/partition-store/partition-store.md) — _(no submodules)_- [partition-store](./src/partitions/partition-store/partition-store.md) — _(no submodules)_- [grants](./src/sharing/grants/grants.md) — _(no submodules)_- [grants](./src/sharing/grants/grants.md) — _(no submodules)_- [tokens](./src/sharing/tokens/tokens.md) — _(no submodules)_- [tokens](./src/sharing/tokens/tokens.md) — _(no submodules)_- [transfer](./src/transfer/transfer/transfer.md) — _(no submodules)_- [transfer](./src/transfer/transfer/transfer.md) — _(no submodules)_- [common](./src/types/common.md) — This module declares the foundational types shared by every other module in `@suaveplan/drive-sharing`. It owns the bra…

• schemas — This module declares Zod schemas for every public option type accepted by @suaveplan/drive-sharing. Schemas are wired…
• error-codes — The error-codes module is the single source of truth for every failure category emitted by @suaveplan/drive-sharing…
• envelope — (no submodules)- key-ring — (no submodules)- key-ring — (no submodules)- otel — (no submodules)- instruments — (no submodules)- partition-manager — (no submodules)- partition-manager — (no submodules)- partition-policy — (no submodules)- partition-policy — (no submodules)- partition-store — (no submodules)- partition-store — (no submodules)- grants — (no submodules)- grants — (no submodules)- tokens — (no submodules)- tokens — (no submodules)- transfer — (no submodules)- transfer — (no submodules)- common — This module declares the foundational types shared by every other module in @suaveplan/drive-sharing. It owns the bra…
• schemas — This module declares Zod schemas for every public option type accepted by @suaveplan/drive-sharing. Schemas are wired…
• error-codes — The error-codes module is the single source of truth for every failure category emitted by @suaveplan/drive-sharing…
• envelope — (no submodules)- key-ring — (no submodules)- key-ring — (no submodules)- otel — (no submodules)- instruments — (no submodules)- partition-manager — (no submodules)- partition-manager — (no submodules)- partition-policy — (no submodules)- partition-policy — (no submodules)- partition-store — (no submodules)- partition-store — (no submodules)- grants — (no submodules)- grants — (no submodules)- tokens — (no submodules)- tokens — (no submodules)- transfer — (no submodules)- transfer — (no submodules)- common — This module declares the foundational types shared by every other module in @suaveplan/drive-sharing. It owns the bra…
• schemas — This module declares Zod schemas for every public option type accepted by @suaveplan/drive-sharing. Schemas are wired…
• error-codes — The error-codes module is the single source of truth for every failure category emitted by @suaveplan/drive-sharing…
• envelope — (no submodules)- key-ring — (no submodules) - key-ring — (no submodules)- otel — (no submodules) - instruments — (no submodules)- partition-manager — (no submodules) - partition-manager — (no submodules)- partition-policy — (no submodules) - partition-policy — (no submodules)- partition-store — (no submodules) - partition-store — (no submodules)- grants — (no submodules) - grants — (no submodules)- tokens — (no submodules) - tokens — (no submodules)- transfer — (no submodules) - transfer — (no submodules)- common — This module declares the foundational types shared by every other module in @suaveplan/drive-sharing. It owns the bra…
• schemas — This module declares Zod schemas for every public option type accepted by @suaveplan/drive-sharing. Schemas are wired…
• error-codes — The error-codes module is the single source of truth for every failure category emitted by @suaveplan/drive-sharing…

Install

bun add @suaveplan/drive-sharing

Quick start

import {
    GrantManager,
    InMemoryPartitionStore,
    KeyRing,
    PartitionManager,
    TokenManager,
    TransferManager,
    envelopeEncrypt,
    envelopeDecrypt,
    fileId,
    partitionId,
    userId,
    wrapKey,
} from "@suaveplan/drive-sharing";

const keyRing = new KeyRing();
const partitions = new PartitionManager({
    store: new InMemoryPartitionStore(),
    keyRing,
});

const partition = await partitions.create({
    name: "research",
    type: "shared",
    ownerId: userId("alice"),
});

const grants = new GrantManager();
const tokens = new TokenManager();

Modules

Subpath	Purpose
@suaveplan/drive-sharing	Default barrel — re-exports every public type and class.
@suaveplan/drive-sharing/errors	DriveShareError, DRIVE_SHARE_CODES.
@suaveplan/drive-sharing/constants	TTL defaults, format version, scalability caps.
@suaveplan/drive-sharing/types/common	Branded IDs, wire types, Result, generateId.
@suaveplan/drive-sharing/types/schemas	Zod schemas for every public option type.
@suaveplan/drive-sharing/encryption/envelope	envelopeEncrypt, envelopeDecrypt, wrapKey, unwrapKey, rewrapKey, WebCryptoProvider.
@suaveplan/drive-sharing/encryption/key-ring	KeyRing with add / get / remove / rotate / export / import.
@suaveplan/drive-sharing/partitions/partition-policy	createPolicy, validateAction, DEFAULT_PRESETS.
@suaveplan/drive-sharing/partitions/partition-store	PartitionStore interface, InMemoryPartitionStore.
@suaveplan/drive-sharing/partitions/partition-manager	PartitionManager lifecycle.
@suaveplan/drive-sharing/sharing/grants	GrantManager (in-memory grants with check / revoke / list).
@suaveplan/drive-sharing/sharing/tokens	TokenManager (HMAC-SHA-256 integrity-tagged tokens).
@suaveplan/drive-sharing/transfer	TransferManager (cross-partition rewrap with AbortSignal).
@suaveplan/drive-sharing/otel	OTel instrument singletons.

Security model

• AAD is mandatory — every envelopeEncrypt and wrapKey call requires a non-empty aad: Uint8Array. Empty AAD throws SHARE_ENCRYPTION_FAILED to enforce the partition-binding guarantee.
• No plaintext keys leave the package — KeyRing.rotateKey zeroizes its caller-supplied buffer; rewrapKey zeroizes the intermediate plaintext DEK before returning.
• HMAC-SHA-256 token integrity — every share token carries an integrity tag computed under the partition master key. Tampering invalidates the tag.
• No key material in events / spans / logs — every event payload carries IDs only.

Performance baselines

Benchmark	Iteration	Wall-clock
grant_check_10k	10 000 in-memory grant checks	< 50 ms
token_validate_10k	10 000 in-memory token validations	< 50 ms
envelope_encrypt_1mb	one 1 MiB AES-GCM encrypt	< 10 ms
envelope_decrypt_1mb	one 1 MiB AES-GCM decrypt	< 10 ms
keyring_rotate_1000	1 000 rotateKey calls	< 250 ms

Run benchmarks with bun run src/__benchmarks__/drive-sharing.bench.ts.

Testing posture

• 100% statement / branch / function / line coverage (Istanbul).
• Property-based tests via fast-check covering grant expiry, token revocation finality, policy merge commutativity, and partition-member invariants.
• All test files import runner primitives from @suaveplan/testing/runner for dual vitest + bun:test portability.

License

Proprietary — Suaveplan commercial license.