@filoz/keysmith

Interfaces

Interface	Description
Claim	One link: what its bearer may read, and how much further they may delegate.
ClaimChain	A chain, root first, with the fields every link inherits from the root.
ClaimSigner	Anything that signs EIP-712 typed data: a viem account or wallet client.
Grant	A node key wrapped to one recipient. Safe to store or send anywhere.
GrantDescriptor	Encryption grant metadata. Exactly these fields are authenticated, so a grant cannot be relabelled; anything else carried alongside a grant is informational and unauthenticated.
KeyspaceKeys	What keyspaceKeys() hands back. The signature it came from is never exposed.
KeyspaceKeysOptions	-
KeyspaceRef	Identifies the keyspace a key belongs to.
PieceLabels	The labels a provider read from a piece’s FEE envelope.
ReadRequest	A request for one piece, from whichever provider holds it, signed by the chain’s final bearer.
TypedDataSigner	Anything that can sign EIP-712 typed data: a viem Account, a WalletClient, or a session key. Keysmith itself never sees a private key.
VerifiedClaim	The final claim of a verified chain.
WriteTarget	What writeTarget() hands a delegate: everything needed to write one piece.

Type Aliases

Type Alias	Description
GrantNode	What a grant may unlock: the whole keyspace, one scope within it, or one piece, named by its salt.
Holding	Which node the caller holds when deriving a piece key: the keyspace, a scope by its path, or one piece by its salt.
KeyspaceKeyMessage	The message an owner signs to start the derivation tree
PieceMetadata	FEE envelope entries to enable key derivation/recovery

Variables

Variable	Description
COMMITMENT_KEY	The FWSS data-set metadata key the commitment is written to.
DOMAIN	Sparse EIP-712 message block to be signed by the root wallet. Note: Deliberately carries neither chainId nor verifyingContract as out primary concern is long-term access to the stored pieces, no matter what chain or contract they were initially associated with.
KEYSPACE_ID_KEY	The FWSS data-set metadata key naming the keyspace, so the chain alone can list them.
KEYSPACE_KEY_TYPES	Parameters of the typed data signature that roots a keyspace
MAX_CHAIN_LENGTH	-
MAX_REQUEST_LIFETIME	-
READ_GRANT_TYPES	EIP-712 types for every link and for a request. The domain is Keysmith’s DOMAIN. A link’s signature covers the fields it inherits from the root, so a link cannot be moved under a root that differs in any of them. Links name their parent by its bearer’s address, not by hash, so a parent can be re-issued without invalidating the links beneath it.
READ_REQUEST_TYPES	-

Functions

Function	Description
commitment	A non-secret commitment to the keyspace key, for FWSS data-set metadata: v1.<32 hex digits>, where v1 is the format of the value.
decodeDelivery	-
decodeGrant	Read a grant delivered as bytes, without opening it: to see what it names before unwrapping, or to pass to holdingOf.
decodePresentation	-
delegateClaim	Delegate: the chain’s final bearer signs a narrower link for bearer. Takes the key the bearer holds for its own link, checks it against that link’s commitment, and derives the child’s key from it, so an honest delegate cannot commit to a wrong key. Hands the child key back to wrap. A piece link needs the piece’s labels, to check the parent’s node reaches it.
encodeDelivery	A delivery: sent once to a new bearer, never to a provider. Carries the v1 grant that wraps the key. The grant must name the chain’s final node, owner and keyspace; that the wrapped key matches the link’s commitment is checked by openDelivery, which holds the private key to unwrap it.
encodeGrant	Pack the grant to deliver or store it
encodePresentation	A presentation: sent to a provider with each gated request, as Authorization: FOC-Grant <base64url>.
grantDescriptor	The descriptor naming what a grant unlocks, ready for wrapTo().
holdingOf	Which node a grant carries, ready to pass to keyForEnvelope.
keyCommitmentOf	A key’s commitment as the 16 bytes a claim carries.
keyForEnvelope	Derive a piece’s key from whichever node the caller holds.
keyResolver	A FEE key resolver for pieces this node reaches: pass it to fee.decrypt(), which calls it with the envelope’s metadata before decrypting a byte.
keyspaceId	Canonical form of a keyspace identifier: 16 bytes of hex, lowercase, prefixed with 0x.
keyspaceKeyMessage	-
keyspaceKeys	Sign for one keyspace and derive its key.
lowSrs	Canonicalize signature:r‖s with s normalised to the low half, and v dropped.
matchesCommitment	Verifies that kk is the key you expect: the right root wallet and the right keyspace. Check this before using any key received in a grant.
newKeyspace	A fresh keyspace identifier: 16 random bytes. Must be unique to a wallet, so that a grant for one keyspace cannot be relabelled as another.
newSalt	A fresh per-piece salt. Public: it only has to travel with the piece.
openDelivery	Open a delivery as its final bearer: verify the chain, unwrap the key, and check it against the commitment in its claim, which the owner (or the delegate above) signed. The keyspace commitment comes back too, for a bearer that writes the keyspace’s first datasets.
pieceKey	The key for one piece. Never reused: FEE requires a fresh key per object.
pieceMetadata	Piece FEE envelope metadata entries.
pieceNode	The grant node for one piece, from its envelope metadata: piece:<salt>.
publicKeyOf	The public key a sender wraps to, for the holder of a secp256k1 private key.
reaches	Whether node reaches the piece these labels describe.
rootClaim	The root of a chain, signed by the owner’s wallet: one EIP-712 prompt. Derives the bearer’s node key from the keyspace key, so the root cannot commit to a wrong one, and hands it back to wrap for the bearer. When the bearer is a session key, set expires to the session key’s expiry.
scopeKey	The key for an access scope. Scopes form a tree, and a scope’s key is derived from its parent’s, so holding a scope also opens every scope beneath it.
scopeName	Canonicalize scope name in the form it is derived from: Unicode NFC, non-empty, no leading or trailing whitespace, and no / (which would indicate a path). Case is significant.
scopePath	Canonicalize scope path: canonical names joined by /, top scope first.
signRequest	Sign a request for one piece, as the chain’s final bearer. Any provider holding it may serve it.
unwrapWith	Open a grant with the recipient’s private key: the grant as delivered, in bytes, or as decoded by decodeGrant.
verifyChain	Check a chain with nothing but the chain: the root signed by the owner and unexpired, every later link signed by the previous bearer and no wider than it. Pass piece when a link names a piece.
verifyPresentation	What a gating provider checks on a request, with only the header and the piece’s labels: the chain, the request’s piece, lifetime and signer, and that the final node reaches the piece. A piece without foc/own is not gated.
wrapTo	Wrap a node key — a keyspace key, a scope key, or one piece’s key — to a recipient.
writeTarget	Everything a delegate needs to write a piece, taken from the grant that delegated it: the keyspace to record, the scope to label it with, and the key to derive its piece key from.