flowstate-crypto Package Skill

Package: @epicdm/flowstate-crypto Repository: epic-flowstate-community Path: packages/flowstate-crypto Version: 1.0.7

Use this published Dojo skill as the package-level entrypoint. For detailed workflows, use the package-local skills listed below.

Primary Package Workflow

Crypto Contract Reference

Use this skill when reviewing whether a caller is honoring FlowState crypto data shapes and runtime contracts.

Field Envelope

EncryptedFieldValue uses:

• __encrypted: true
• v: 1
• alg: 'AES-256-GCM'
• scope
• keyId
• optional kv
• dk
• ct
• iv
• at

Owner scope uses RSA-OAEP wrapped DEKs. Group scope uses colon-delimited AES-GCM wrapped DEKs.

File Envelope

EncryptedFileResult uses ciphertext bytes plus base64 iv, authTag, scope, keyId, and wrappedDEK.

Persist document encryption metadata with enough information to pair the ciphertext and wrapping key.

Provider Records

fetchUserKey must return encrypted private key fields, public key, algorithm, key type, and either PBKDF2 or agent salt data.

fetchVaultMemberships returns vault group wraps.

fetchEncryptionKeys returns records whose keyWraps field is a JSON string, not an array.

Runtime Assumptions

The package expects Web Crypto through globalThis.crypto, plus TextEncoder and TextDecoder. Base64 helpers may rely on browser APIs or Node Buffer.

Error Semantics

• Locked KeyRing operations throw.
• decryptFields masks locked values with [encrypted].
• decryptFields masks unknown encrypted versions with [undecryptable].
• KeyRing.decryptField throws on unsupported versions.
• Missing group keys throw by key ID.

Package Skill Inventory

Package Skill Inventory: @epicdm/flowstate-crypto

Package path: packages/flowstate-crypto.

Skill Map

Anti-Sprawl Decision

Do not create one skill per exported primitive. Agents need operational vault workflows: unlock, field encryption, file encryption, key provisioning, envelope sharing, contracts, and maintenance.

Deferred Skills

• Dedicated AES/RSA/PBKDF2/HKDF primitive skills: defer unless these primitives become public workflows independent of vault behavior.
• Dedicated recovery-key-only skill: fold into key provisioning until recovery UI and API workflows need a separate course.

Review Gate

Package Skill Review: @epicdm/flowstate-crypto

Package path: packages/flowstate-crypto.

Review Result

Status: drafted, source-backed, verified, pending publication.

The skillset is workflow-shaped around KeyRing, field encryption, file encryption, key provisioning, envelope sharing, contracts, and maintenance. It intentionally does not mirror the feature matrix one exported function at a time.

Checks

• Source review: completed from package source, tests, downstream integration notes, and generated artifact drift.
• Skill inventory: completed.
• Skill files: completed.
• ASCII/frontmatter scan: passed.
• Package tests: passed, 12 suites and 114 tests.
• Package typecheck: passed.
• Package build: passed.
• Package lint: passed with 12 existing warnings.
• Generated Dojo replacement: pending.
• Cloud Dojo publication: pending.

Verification Commands

Run before publication:

yarn workspace @epicdm/flowstate-crypto test --runInBand
yarn workspace @epicdm/flowstate-crypto typecheck
yarn workspace @epicdm/flowstate-crypto build
yarn workspace @epicdm/flowstate-crypto lint

Recommended downstream reference check:

rg -n "@epicdm/flowstate-crypto|KeyRing|EncryptedFieldValue|DocumentEncryptionMeta" packages docker docs .flowstate

Publication Gate

Do not publish the existing generated .flowstate/dojo package as-is. Publish only after Dojo lessons are rebuilt from these reviewed package skills.

Start with this skill to understand the package purpose, then use the package-local focused skills for specific workflows. Keep this Dojo version aligned with packages/flowstate-crypto/package.json. Do not treat generated feature lists as lessons; use workflow evidence from CODE-REVIEW.md, SKILL-INVENTORY.md, and REVIEW.md.